From c9338891d5034b52073411db30db4143a3108124 Mon Sep 17 00:00:00 2001 From: Pierre Krieger Date: Thu, 9 Feb 2017 14:02:38 +0100 Subject: [PATCH] More documentation rework --- .travis.yml | 10 +---- Cargo.toml | 2 +- README.md | 5 +-- src/conversions/sample.rs | 13 ++++++- src/decoder/mod.rs | 2 + src/lib.rs | 82 ++++++++++++++++++++++++++------------- src/source/mod.rs | 2 + 7 files changed, 74 insertions(+), 42 deletions(-) diff --git a/.travis.yml b/.travis.yml index 187eec7..8d9b3e6 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,15 +16,7 @@ addons: packages: - libasound2-dev -after_success: - - | - [ $TRAVIS_BRANCH = master ] && - [ $TRAVIS_PULL_REQUEST = false ] && - [ $TRAVIS_RUST_VERSION = nightly ] && - cargo doc && - git clone https://github.com/davisp/ghp-import && - ./ghp-import/ghp-import target/doc && - git push -fq https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages +after_success: - | [ $TRAVIS_BRANCH = master ] && [ $TRAVIS_PULL_REQUEST = false ] && diff --git a/Cargo.toml b/Cargo.toml index 8fe925c..5ad7b21 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -6,7 +6,7 @@ license = "Apache-2.0" description = "Audio playback library" keywords = ["audio", "playback", "gamedev"] repository = "https://github.com/tomaka/rodio" -documentation = "http://tomaka.github.io/rodio/rodio/index.html" +documentation = "http://docs.rs/rodio" [dependencies] cpal = "0.4.0" diff --git a/README.md b/README.md index 3464493..2beb5c6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ # Audio playback library [![Build Status](https://travis-ci.org/tomaka/rodio.svg?branch=master)](https://travis-ci.org/tomaka/rodio) - [![](http://meritbadge.herokuapp.com/rodio)](https://crates.io/crates/rodio) Rust playback library. @@ -10,6 +9,6 @@ Rust playback library. - WAV decoding is handled by [hound](https://github.com/ruud-v-a/hound). - Vorbis decoding is handled by [lewton](https://github.com/est31/lewton). -## [Documentation](http://tomaka.github.io/rodio/rodio/index.html) +# [Documentation](http://docs.rs/rodio) -See the documentation for usage. +[The documentation](http://docs.rs/rodio) contains an introduction to the library. diff --git a/src/conversions/sample.rs b/src/conversions/sample.rs index 1fc0bcf..95dde61 100644 --- a/src/conversions/sample.rs +++ b/src/conversions/sample.rs @@ -52,8 +52,19 @@ impl ExactSizeIterator for DataConverter { } - /// Represents a value of a single sample. +/// +/// This trait is implemented by default on three types: `i16`, `u16` and `f32`. +/// +/// - For `i16`, silence corresponds to the value `0`. The minimum and maximum amplitudes are +/// represented by `i16::min_value()` and `i16::max_value()` respectively. +/// - For `u16`, silence corresponds to the value `u16::max_value() / 2`. The minimum and maximum +/// amplitudes are represented by `0` and `u16::max_value()` respectively. +/// - For `f32`, silence corresponds to the value `0.0`. The minimum and maximum amplitudes are +/// represented by `-1.0` and `1.0` respectively. +/// +/// You can implement this trait on your own type as well if you wish so. +/// pub trait Sample: cpal::Sample + Add + AddAssign { /// Linear interpolation between two samples. /// diff --git a/src/decoder/mod.rs b/src/decoder/mod.rs index 9553087..cd495c4 100644 --- a/src/decoder/mod.rs +++ b/src/decoder/mod.rs @@ -1,3 +1,5 @@ +//! Decodes samples from an audio file. + use std::error::Error; use std::fmt; use std::io::{Read, Seek}; diff --git a/src/lib.rs b/src/lib.rs index f4cdea0..58e57c7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,55 +1,81 @@ -//! # Usage +//! Audio playback library. //! -//! There are two main concepts in this library: +//! The main concept of this library is [the `Source` trait](source/trait.Source.html), which +//! represents a sound (streaming or not). In order to play a sound, there are three steps: //! -//! - Sources, represented with [the `Source` trait](source/trait.Source.html), that provide sound -//! data. -//! - Sinks, which accept sound data. +//! - Create an object that represents the streaming sound. It can be a sine wave, a buffer, a +//! [decoder](decoder/index.html), etc. or even your own type that implements +//! [the `Source` trait](source/trait.Source.html). +//! - Choose an output which the [`get_endpoints_list`](fn.get_endpoints_list.html) or +//! [`get_default_endpoint`](fn.get_default_endpoint.html) functions. +//! - Call [`play_raw(output, source)`](fn.play_raw.html). //! -//! > **Note**: If you are not familiar with what a sound is or how a sound is stored in memory, -//! > check out the documentation of [the `Source` trait](source/trait.Source.html). -//! -//! In order to play a sound, you need to create a source, a sink, and connect the two. For example -//! here is how you play a sound file: +//! For example, here is how you would play an audio file: //! //! ```no_run +//! use std::fs::File; //! use std::io::BufReader; //! //! let endpoint = rodio::get_default_endpoint().unwrap(); -//! let sink = rodio::Sink::new(&endpoint); //! -//! let file = std::fs::File::open("music.ogg").unwrap(); +//! let file = File::open("sound.ogg").unwrap(); //! let source = rodio::Decoder::new(BufReader::new(file)).unwrap(); +//! rodio::play_raw(&endpoint, source); +//! ``` +//! +//! ## Sink +//! +//! In order to make it easier to control the playback, the rodio library also provides a type +//! named [`Sink`](struct.Sink.html) which represents an audio track. +//! +//! Instead of playing the sound with [`play_raw`](fn.play_raw.html), you can add it to a +//! [`Sink`](struct.Sink.html) instead. +//! +//! ```no_run +//! use rodio::Sink; +//! +//! let endpoint = rodio::get_default_endpoint().unwrap(); +//! let sink = Sink::new(&endpoint); +//! +//! // Add a dummy source of the sake of the example. +//! let source = rodio::source::SineWave::new(440); //! sink.append(source); //! ``` //! -//! The `append` method takes ownership of the source and starts playing it. If a sink is already -//! playing a sound when you call `append`, the sound is added to a queue and will start playing -//! when the existing source is over. +//! The [`append` method](struct.Sink.html#method.append) will add the sound at the end of the +//! sink. It will be played when all the previous sounds have been played. If you want multiple +//! sounds to play simultaneously, you should create multiple [`Sink`](struct.Sink.html)s. //! -//! If you want to play multiple sounds simultaneously, you should create multiple sinks. +//! The [`Sink`](struct.Sink.html) type also provides utilities such as playing/pausing or +//! controlling the volume. //! -//! # How it works +//! ## Filters //! -//! Rodio spawns a background thread that is dedicated to reading from the sources and sending -//! the output to the endpoint. -//! -//! All the sounds are mixed together by rodio before being sent. Since this is handled by the -//! software, there is no restriction for the number of sinks that can be created. -//! -//! # Adding effects -//! -//! The `Source` trait provides various filters, similarly to the standard `Iterator` trait. +//! [The `Source` trait](source/trait.Source.html) provides various filters, similarly to the +//! standard `Iterator` trait. //! //! Example: //! -//! ```ignore +//! ``` //! use rodio::Source; //! use std::time::Duration; //! -//! // repeats the first five seconds of this sound forever +//! // Repeats the first five seconds of the sound forever. +//! # let source = rodio::source::SineWave::new(440); //! let source = source.take_duration(Duration::from_secs(5)).repeat_infinite(); //! ``` +//! +//! ## How it works under the hood +//! +//! Rodio spawns a background thread that is dedicated to reading from the sources and sending +//! the output to the endpoint. Whenever you give up ownership of a `Source` in order to play it, +//! it is sent to this background thread where it will be read by rodio. +//! +//! All the sounds are mixed together by rodio before being sent to the operating system or the +//! hardware. Therefore there is no restriction on the number of sounds that play simultaneously or +//! the number of sinks that can be created (except for the fact that creating too many will slow +//! down your program). +//! #![cfg_attr(test, deny(missing_docs))] diff --git a/src/source/mod.rs b/src/source/mod.rs index 763c3e1..bd97edf 100644 --- a/src/source/mod.rs +++ b/src/source/mod.rs @@ -1,3 +1,5 @@ +//! Sources of sound and various filters. + use std::time::Duration; use Sample;