docs: lib.rs

kxxt · Jun 26, 2023 · fc4a780 · fc4a780
1 parent f82f03c
commit fc4a780
Showing 1 changed file with 98 additions and 0 deletions.
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,3 +1,101 @@
+//! A simple text-to-speech client for Azure TTS API.
+//!
+//! This crate provides the client binding for Azure TTS API. It supports both RESTful API and Websocket API.
+//!
+//! # Quick Start
+//!
+//! First, you need to setup authentication and select an audio format.
+//! Here we will use an Azure subscription key, but you can also use an auth token.
+//!
+//! ```ignore
+//! use aspeak::{synthesizer::SynthesizerConfig, AudioFormat, AuthOptionsBuilder};
+//! use aspeak::{get_rest_endpoint_by_region, get_websocket_endpoint_by_region};
+//!
+//! let auth = AuthOptionsBuilder::new(
+//!     // Choose one of the following endpoints based on your selected API.
+//!     // get_rest_endpoint_by_region("eastus"), // for RESTful API
+//!     // get_websocket_endpoint_by_region("eastus") // for Websocket API
+//! )
+//! .key("YOUR_AZURE_SUBSCRIPTION_KEY")
+//! .build();
+//! let config = SynthesizerConfig::new(auth, AudioFormat::Riff16Khz16BitMonoPcm);
+//! ```
+//!
+//! ## RESTful Synthesizer
+//!
+//! Then, you can create a [RestSynthesizer][crate::synthesizer::RestSynthesizer]
+//! from the [SynthesizerConfig][crate::synthesizer::SynthesizerConfig].
+//!
+//! ```ignore
+//! let rest_syn = config.rest_synthesizer()?;
+//! ```
+//!
+//! Now you can synthesize SSML to audio data.
+//!
+//! ```ignore
+//! let ssml = r#"<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US"><voice name="en-US-JennyNeural">Hello, world!</voice></speak>"#;
+//! let audio_data = rest_syn.synthesize_ssml(ssml).await?;
+//! ```
+//!
+//! Or you can synthesize text with [TextOptions][crate::TextOptions].
+//!
+//! ```ignore
+//! use aspeak::TextOptionsBuilder;
+//! let text = "Hello, world!";
+//! let options = TextOptionsBuilder::new().voice("en-US-JennyNeural").rate("fast").pitch("high").build();
+//! let audio_data = rest_syn.synthesize_text(text, &options).await?;
+//! ```
+//!
+//! The full code can be found in [examples/03-rest-synthesizer-simple.rs](https://github.com/kxxt/aspeak/blob/main/examples/03-rest-synthesizer-simple.rs)
+//!
+//! ## Websocket Synthesizer
+//!
+//! You can also create a [WebsocketSynthesizer][crate::synthesizer::WebsocketSynthesizer].
+//!
+//! ```ignore
+//! let mut ws_syn = config.connect_websocket().await?;
+//! ```
+//!
+//! Then you can synthesize SSML to audio data.
+//!
+//! ```ignore
+//! let ssml = r#"<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US"><voice name="en-US-JennyNeural">Hello, world!</voice></speak>"#;
+//! let audio_data = ws_syn.synthesize_ssml(ssml).await?;
+//! ```
+//!
+//! or synthesize text with [TextOptions][crate::TextOptions].
+//!
+//! ```ignore
+//! use aspeak::TextOptionsBuilder;
+//! let text = "Hello, world!";
+//! let options = TextOptionsBuilder::new().voice("en-US-JennyNeural").rate("fast").pitch("high").build();
+//! let audio_data = ws_syn.synthesize_text(text, &options).await?;
+//! ```
+//!
+//! The full code can be found in [examples/04-websocket-synthesizer-simple.rs](https://github.com/kxxt/aspeak/blob/main/examples/04-websocket-synthesizer-simple.rs)
+//!
+//! # Unified synthesizer trait
+//!
+//! There is also a unified synthesizer trait [Synthesizer][crate::synthesizer::UnifiedSynthesizer] that can be used to
+//! provide a unified interface for both RESTful and Websocket synthesizers.
+//!
+//! # TLS feature flags
+//!
+//! By default, this crate uses `native-tls`. To use other TLS implementations, you can use the following feature flags:
+//!
+//! - `native-tls-vendored`: Use the vendored version of `native-tls`.
+//! - `rustls-tls-native-roots`
+//! - `rustls-tls-webpki-roots`
+//!
+//! Note that you need to disable the default features to disable `native-tls`. And after that, you need to manually enable your desired synthesizer features.
+//!
+//! # Feature flags
+//!
+//! - `rest-synthesizer`: Enable the RESTful synthesizer.
+//! - `websocket-synthesizer`: Enable the Websocket synthesizer.
+//! - `unified-synthesizer`: Enable the unified synthesizer trait.
+//! - `synthesizers`: Enable all synthesizers.
+
 mod audio;
 mod auth;
 mod constants;