diff --git a/README.md b/README.md index 76016c1da..4ce592b2d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![docs-badge][]][docs] [![build badge]][build] [![guild-badge][]][guild] [![crates.io version]][crates.io link] [![rust 1.61.0+ badge]][rust 1.61.0+ link] +[![docs-badge][]][docs] [![next-docs-badge][]][next-docs] [![build badge]][build] [![guild-badge][]][guild] [![crates.io version]][crates.io link] [![rust 1.61.0+ badge]][rust 1.61.0+ link] # Songbird @@ -86,9 +86,12 @@ Songbird's logo is based upon the copyright-free image ["Black-Capped Chickadee" [build badge]: https://img.shields.io/github/workflow/status/serenity-rs/songbird/CI?style=flat-square [build]: https://github.com/serenity-rs/songbird/actions -[docs-badge]: https://img.shields.io/badge/docs-online-4d76ae.svg?style=flat-square +[docs-badge]: https://img.shields.io/badge/docs-current-4d76ae.svg?style=flat-square [docs]: https://serenity-rs.github.io/songbird/current +[next-docs-badge]: https://img.shields.io/badge/docs-next-4d76ae.svg?style=flat-square +[next-docs]: https://serenity-rs.github.io/songbird/next + [guild]: https://discord.gg/9X7vCus [guild-badge]: https://img.shields.io/discord/381880193251409931.svg?style=flat-square&colorB=7289DA diff --git a/src/input/mod.rs b/src/input/mod.rs index 2d4228878..8bd41d7e4 100644 --- a/src/input/mod.rs +++ b/src/input/mod.rs @@ -144,6 +144,8 @@ use tokio::runtime::Handle as TokioHandle; /// /// // If we want to inspect metadata (and we can't use AuxMetadata for any reason), we have /// // to parse the track ourselves. +/// // +/// // We can access it on a live track using `TrackHandle::action()`. /// in_memory_input = in_memory_input /// .make_playable_async(&CODEC_REGISTRY, &PROBE) /// .await diff --git a/src/serenity.rs b/src/serenity.rs index 588e75ff7..978833a23 100644 --- a/src/serenity.rs +++ b/src/serenity.rs @@ -1,7 +1,7 @@ -//! Compatability and convenience methods for working with [serenity]. +//! Compatibility and convenience methods for working with [serenity]. //! Requires the `"serenity"` feature. //! -//! [serenity]: https://crates.io/crates/serenity/0.9.0-rc.2 +//! [serenity]: https://crates.io/crates/serenity use crate::{Config, Songbird}; use serenity::{ diff --git a/src/tracks/handle.rs b/src/tracks/handle.rs index ee893c79e..746db3d57 100644 --- a/src/tracks/handle.rs +++ b/src/tracks/handle.rs @@ -15,8 +15,6 @@ use uuid::Uuid; /// Many method calls here are fallible; in most cases, this will be because /// the underlying [`Track`] object has been discarded. Those which aren't refer /// to shared data not used by the driver. -/// -/// [`Track`]: Track pub struct TrackHandle { inner: Arc, } diff --git a/src/tracks/mod.rs b/src/tracks/mod.rs index 3d175c20d..23b1a43e4 100644 --- a/src/tracks/mod.rs +++ b/src/tracks/mod.rs @@ -1,18 +1,20 @@ //! Live, controllable audio instances. //! //! Tracks add control and event data around the bytestreams offered by [`Input`], -//! where each represents a live audio source inside of the driver's mixer. +//! where each represents a live audio source inside of the driver's mixer. This includes +//! play state, volume, and looping behaviour. //! -//! To prevent locking and stalling of the driver, tracks are controlled from your bot using a -//! [`TrackHandle`]. These handles remotely send commands from your bot's (a)sync -//! context to control playback, register events, and execute synchronous closures. +//! To configure an audio source as it is created, you can create a [`Track`] to set the +//! above playback state [from any `Input` or `T: Into`](Track#trait-implementations) +//! using `Track::from(...)`. //! -//! If you want a new track from an [`Input`], i.e., for direct control before -//! playing your source on the driver, use [`create_player`]. +//! To configure an audio source once it has been given to a [`Driver`], you are given a +//! [`TrackHandle`] once you hand the [`Input`] and state over to be played. These handles +//! remotely send commands from your bot's (a)sync context to control playback, register events, +//! and execute synchronous closures. This design prevents user code from being able to lock +//! or stall the audio mixer. //! -//! [`Input`]: ../input/struct.Input.html -//! [`TrackHandle`]: struct.TrackHandle.html -//! [`create_player`]: fn.create_player.html +//! [`Driver`]: crate::driver::Driver mod action; mod command; @@ -47,7 +49,7 @@ use uuid::Uuid; /// [`Track`]s allow you to configure play modes, volume, event handlers, and other track state /// before you pass an input to the [`Driver`]. /// -/// Live track data is accesseed via a [`TrackHandle`], returned by [`Driver::play`] and +/// Live track data is accessed via a [`TrackHandle`], which is returned by [`Driver::play`] and /// related methods. /// /// # Example @@ -55,15 +57,13 @@ use uuid::Uuid; /// ```rust,no_run /// use songbird::{driver::Driver, input::File, tracks::Track}; /// -/// # async { /// // A Call is also valid here! -/// let mut handler: Driver = Default::default(); +/// let mut driver: Driver = Default::default(); /// let source = File::new("../audio/my-favourite-song.mp3"); /// -/// handler.play_only(Track::new(source.into()).volume(0.5)); +/// let handle = driver.play_only(Track::from(source).volume(0.5)); /// -/// // Future access occurs via audio_handle. -/// # }; +/// // Future access occurs via audio. /// ``` /// /// [`Driver`]: crate::driver::Driver