songbird/
lib.rs

1#![doc(
2    html_logo_url = "https://raw.githubusercontent.com/serenity-rs/songbird/current/songbird.png",
3    html_favicon_url = "https://raw.githubusercontent.com/serenity-rs/songbird/current/songbird-ico.png"
4)]
5#![cfg_attr(docsrs, feature(doc_auto_cfg))]
6#![deny(missing_docs)]
7#![deny(rustdoc::broken_intra_doc_links)]
8//! ![project logo][logo]
9//!
10//! Songbird is an async, cross-library compatible voice system for Discord, written in Rust.
11//! The library offers:
12//!  * A standalone gateway frontend compatible with [serenity] and [twilight] using the
13//!    `"gateway"` and `"[serenity/twilight]"` plus `"[rustls/native]"` features. You can even run
14//!    driverless, to help manage your [lavalink] sessions.
15//!  * A standalone driver for voice calls, via the `"driver"` feature. If you can create
16//!    a `ConnectionInfo` using any other gateway, or language for your bot, then you
17//!    can run the songbird voice driver.
18//!  * Voice receive and RT(C)P packet handling via the `"receive"` feature.
19//!  * And, by default, a fully featured voice system featuring events, queues,
20//!    seeking on compatible streams, shared multithreaded audio stream caches,
21//!    and direct Opus data passthrough from DCA files.
22//!
23//! ## Intents
24//! Songbird's gateway functionality requires you to specify the `GUILD_VOICE_STATES` intent.
25//!
26//! ## Examples
27//! Full examples showing various types of functionality and integrations can be found
28//! in [this crate's examples directory].
29//!
30//! ## Codec support
31//! Songbird supports all [codecs and formats provided by Symphonia] (pure-Rust), with Opus support
32//! provided by [audiopus] (an FFI wrapper for libopus).
33//!
34//! **By default, *Songbird will not request any codecs from Symphonia*.** To change this, in your own
35//! project you will need to depend on Symphonia as well.
36//!
37//! ```toml
38//! # Including songbird alone gives you support for Opus via the DCA file format.
39//! [dependencies.songbird]
40//! version = "0.5"
41//! features = ["builtin-queue"]
42//!
43//! # To get additional codecs, you *must* add Symphonia yourself.
44//! # This includes the default formats (MKV/WebM, Ogg, Wave) and codecs (FLAC, PCM, Vorbis)...
45//! [dependencies.symphonia]
46//! version = "0.5"
47//! features = ["aac", "mp3", "isomp4", "alac"] # ...as well as any extras you need!
48//! ```
49//!
50//! ## Attribution
51//!
52//! Songbird's logo is based upon the copyright-free image ["Black-Capped Chickadee"] by George Gorgas White.
53//!
54//! [logo]: https://raw.githubusercontent.com/serenity-rs/songbird/current/songbird.png
55//! [serenity]: https://github.com/serenity-rs/serenity
56//! [twilight]: https://github.com/twilight-rs/twilight
57//! [this crate's examples directory]: https://github.com/serenity-rs/songbird/tree/current/examples
58//! ["Black-Capped Chickadee"]: https://www.oldbookillustrations.com/illustrations/black-capped-chickadee/
59//! [`ConnectionInfo`]: struct@ConnectionInfo
60//! [lavalink]: https://github.com/freyacodes/Lavalink
61//! [codecs and formats provided by Symphonia]: https://github.com/pdeljanov/Symphonia#formats-demuxers
62//! [audiopus]: https://github.com/lakelezz/audiopus
63
64#![warn(clippy::pedantic, rust_2018_idioms)]
65#![allow(
66    // Allowed as they are too pedantic
67    clippy::module_name_repetitions,
68    clippy::wildcard_imports,
69    clippy::too_many_lines,
70    clippy::cast_lossless,
71    clippy::cast_sign_loss,
72    clippy::cast_possible_wrap,
73    clippy::cast_precision_loss,
74    clippy::cast_possible_truncation,
75    // TODO: would require significant rewriting of all existing docs
76    clippy::missing_errors_doc,
77    clippy::missing_panics_doc,
78    clippy::doc_link_with_quotes,
79    clippy::doc_markdown,
80    // Allowed as they cannot be fixed without breaking
81    clippy::result_large_err,
82    clippy::large_enum_variant,
83)]
84
85mod config;
86pub mod constants;
87#[cfg(feature = "driver")]
88pub mod driver;
89pub mod error;
90#[cfg(feature = "driver")]
91pub mod events;
92#[cfg(feature = "gateway")]
93mod handler;
94pub mod id;
95pub(crate) mod info;
96#[cfg(feature = "driver")]
97pub mod input;
98#[cfg(feature = "gateway")]
99pub mod join;
100#[cfg(feature = "gateway")]
101mod manager;
102#[cfg(feature = "serenity")]
103pub mod serenity;
104#[cfg(feature = "gateway")]
105pub mod shards;
106#[cfg(any(test, feature = "internals"))]
107pub mod test_utils;
108#[cfg(feature = "driver")]
109pub mod tracks;
110#[cfg(feature = "driver")]
111mod ws;
112
113#[cfg(all(feature = "driver", feature = "receive"))]
114pub use discortp as packet;
115#[cfg(feature = "driver")]
116pub use serenity_voice_model as model;
117
118pub(crate) use serde_json as json;
119
120#[cfg(feature = "driver")]
121pub use crate::{
122    driver::Driver,
123    events::{CoreEvent, Event, EventContext, EventHandler, TrackEvent},
124};
125
126#[cfg(feature = "gateway")]
127pub use crate::{handler::*, manager::*};
128
129#[cfg(feature = "serenity")]
130pub use crate::serenity::*;
131
132pub use config::Config;
133pub use info::ConnectionInfo;
songbird/lib.rs

songbird/
lib.rs
