ibm_watson/lib.rs
1//! <h1 style="text-align: center">IBM Watson</h1>
2//! <p style="text-align: center">A wrapper for interacting with IBM Watson's API</p>
3//! <div align="center">
4//! <img alt="Crates.io" style="align: center" src="https://img.shields.io/crates/v/ibm-watson">
5//! <img alt="docs.rs" src="https://img.shields.io/docsrs/ibm-watson">
6//! <img alt="GitHub Workflow Status" src="https://img.shields.io/github/workflow/status/kawaki-san/ibm-watson-rs/Cargo%20Build%20&%20Test%20(with%20Docs)">
7//! <img alt="Crates.io" src="https://img.shields.io/crates/l/ibm-watson">
8//! </div>
9//!
10//! # Usage
11//!
12//! Add `ibm-watson` to your `Cargo.toml`
13//!
14//! ```toml
15//! [dependencies]
16//! ibm-watson = "0.1.1"
17//! ```
18//!
19//! # Feature Flags
20//!
21//! This crate uses a set of featue flags to reduce the amount of compiled code. By default, none
22//! of the features are enabled and it is therefore recommended that you do so for only those
23//! services you intend to use.
24//!
25//! * `full` - Enables all the features listed below
26//! * `http2` - Enables support of `HTTP/2.0` requests
27//! * `tts` - Enables interacting with the Text To Speech API
28//!
29//! # Example
30//!
31//! To use the Text To Speech API to synthesise some text with the default options, enable the `tts` feature
32//!
33//! ```toml
34//! [dependencies]
35//! ibm-watson = { version = "0.1.1", features = [ "tts" ] }
36//! ```
37//!
38//! ``` no_run
39//!# use std::{fs::File, io::Write};
40//!# use ibm_watson::{
41//!# auth::IamAuthenticator,
42//!# tts::TextToSpeech
43//!# };
44//! # #[tokio::main]
45//! # async fn main() -> Result<(), Box <dyn std::error::Error>> {
46//! // Get your IAM access token with the API Key of the particular service you want to use
47//! let auth = IamAuthenticator::new("my_api_key").await?;
48//! // Create a new Text To Speech instance that you will use to interact with the API
49//! let tts = TextToSpeech::new(&auth, "tts-endpoint");
50//! // Call whatever method you would like to use from it
51//! let synth = tts.synthesise("Hello world", None, None).await?;
52//! let mut file = File::create("file.ogg")?;
53//! file.write_all(&synth)?;
54//!# Ok(())
55//!# }
56//! ```
57//!
58//! To perform synthesis with a custom voice and in a different audio format:
59//!
60//! ``` no_run
61//!# use std::{fs::File, io::Write};
62//!# use ibm_watson::{
63//!# auth::IamAuthenticator,
64//!# tts::{synthesis::AudioFormat, TextToSpeech,
65//!# voices::WatsonVoice},
66//!# };
67//! # #[tokio::main]
68//! # async fn main() -> Result<(), Box <dyn std::error::Error>> {
69//! # let auth = IamAuthenticator::new("my_api_key").await?;
70//! # let mut tts = TextToSpeech::new(&auth, "tts-endpoint");
71//! // This sets Kate (United Kingdom) to be the default voice for your requests
72//! tts.set_voice(WatsonVoice::EnGbKateV3);
73//! // set the format to MP3 with a sample rate of 44100khz
74//! let format = AudioFormat::AudioMp3 {
75//! // If `None` is passed, then the crate will default to 22050.
76//! sample_rate: Some(44100),
77//! };
78//! let synth = tts.synthesise("Hello world", Some(format), None).await?;
79//! # Ok(())
80//! # }
81//! ```
82//!
83//! There are examples ready to get you started quickly. To run an example that uses the Text To
84//! Speech service to print available voices and then synthesise the text you entered to a file:
85//!
86//! ```sh
87//! cargo run --example tts --features="tts" -- -a "my_api_key" -s "my_service_url" -t "Greetings from Rust"
88//! ```
89//!
90//! # License
91//!
92//! This crate is licensed under either of:
93//!
94//! - Apache License, Version 2.0
95//! - MIT License
96//!
97//! at your option.
98//!
99//! [Apache License, Version 2.0]: http://www.apache.org/licenses/LICENSE-2.0
100//!
101//! [MIT License]: http://opensource.org/licenses/MIT
102//!
103//! # Contribution
104//!
105//! Unless you explicitly state otherwise, any contribution intentionally submitted
106//! for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
107//! dual licensed as above, without any additional terms or conditions.
108//!
109//! <p style="font-style: italic">This is currently unofficial, experimental software that is under development. As such, contributions are welcome.</p>
110//! <p style="font-style: italic">This crate's documentation is sourced from IBM Watson's official <a href = "https://developer.ibm.com/components/watson-apis/apis">API Documentation.</a> If you would like to know more about Watson's API, that would be a good place to start.</p>
111#![cfg_attr(docsrs, feature(doc_cfg))]
112#[warn(
113 missing_debug_implementations,
114 missing_docs,
115 rustdoc::broken_intra_doc_links,
116 // unreachable_pub,
117 // rustdoc::missing_doc_code_examples
118)]
119
120/// Retrieve an IAM access token to use for authentication with your IBM Watson services
121///
122/// # Example
123///
124/// ``` no_run
125/// # use ibm_watson::{
126/// # auth::IamAuthenticator,
127/// # tts::{voices::WatsonVoice, TextToSpeech},
128/// # };
129/// # async fn foo()-> Result<(), Box<dyn std::error::Error>> {
130/// let auth = IamAuthenticator::new("api_key").await?;
131/// # Ok(())
132/// # }
133/// ```
134pub mod auth;
135/// Interact with the IBM Watson™ Text to Speech service
136#[cfg(feature = "tts")]
137#[cfg_attr(docsrs, doc(cfg(feature = "tts")))]
138#[path = "text-to-speech/mod.rs"]
139pub mod tts;
140
141#[cfg(test)]
142mod tests;