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

songbird/
lib.rs
