ferrin_spec/
speech_model.rs

1//! Speech (text-to-speech) model interface.
2
3use std::future::Future;
4
5use bytes::Bytes;
6use serde::Deserialize;
7use serde::Serialize;
8use tokio_util::sync::CancellationToken;
9
10use crate::error::ProviderError;
11use crate::language_model::RequestMetadata;
12use crate::language_model::ResponseMetadata;
13use crate::shared::Headers;
14use crate::shared::MediaType;
15use crate::shared::ModelId;
16use crate::shared::ProviderId;
17use crate::shared::ProviderMetadata;
18use crate::shared::ProviderOptions;
19use crate::shared::Warning;
20use crate::shared::base64_bytes;
21
22/// A model that synthesizes speech from text.
23pub trait SpeechModel: Send + Sync + 'static {
24    /// Provider identifier.
25    fn provider(&self) -> &ProviderId;
26
27    /// Model identifier.
28    fn model_id(&self) -> &ModelId;
29
30    /// Synthesizes `options.text`.
31    fn do_generate(
32        &self,
33        options: SpeechOptions,
34    ) -> impl Future<Output = Result<SpeechResult, ProviderError>> + Send;
35}
36
37/// Options for a speech synthesis call.
38#[derive(Debug, Clone, Default)]
39pub struct SpeechOptions {
40    /// Text to synthesize.
41    pub text: String,
42    /// Voice identifier.
43    pub voice: Option<String>,
44    /// Output format (for example `mp3`, `wav`).
45    pub output_format: Option<String>,
46    /// Style instructions.
47    pub instructions: Option<String>,
48    /// Speed multiplier.
49    pub speed: Option<f64>,
50    /// Language code.
51    pub language: Option<String>,
52    /// Provider-specific options keyed by provider name.
53    pub provider_options: ProviderOptions,
54    /// Additional request headers.
55    pub headers: Headers,
56    /// Cancellation token.
57    pub cancellation: CancellationToken,
58}
59
60impl SpeechOptions {
61    /// Creates options for `text`.
62    #[must_use]
63    pub fn new(text: impl Into<String>) -> Self {
64        Self {
65            text: text.into(),
66            ..Self::default()
67        }
68    }
69}
70
71/// Result of a speech synthesis call.
72#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
73pub struct SpeechResult {
74    /// Audio bytes.
75    #[serde(with = "base64_bytes")]
76    pub audio: Bytes,
77    /// Media type of the audio, if the provider reports it.
78    #[serde(default, skip_serializing_if = "Option::is_none")]
79    pub media_type: Option<MediaType>,
80    /// Warnings.
81    #[serde(default)]
82    pub warnings: Vec<Warning>,
83    /// Request metadata.
84    #[serde(default)]
85    pub request: RequestMetadata,
86    /// Response metadata; `timestamp` and `model_id` are expected to be set.
87    #[serde(default)]
88    pub response: ResponseMetadata,
89    /// Provider-specific metadata.
90    #[serde(default, skip_serializing_if = "Option::is_none")]
91    pub provider_metadata: Option<ProviderMetadata>,
92}
ferrin_spec/speech_model.rs

ferrin_spec/
speech_model.rs
