gemini_live/lib.rs
1//! # gemini-live
2//!
3//! High-performance, idiomatic Rust client for the
4//! [Gemini Multimodal Live API](https://ai.google.dev/api/live).
5//!
6//! Designed for real-time audio/video streaming where every allocation
7//! counts. See [`audio::AudioEncoder`] for the zero-allocation hot path,
8//! `docs/design.md` for performance goals, and `docs/roadmap.md` for
9//! known gaps and planned work.
10//!
11//! ## Architecture
12//!
13//! The crate is organised in layers — each builds on the one below:
14//!
15//! | Layer | Module | Responsibility |
16//! |---------------|---------------|-----------------------------------------------------------------|
17//! | **Session** | [`session`] | Connection lifecycle, reconnection, typed send/receive |
18//! | **Transport** | [`transport`] | WebSocket connection, TLS, frame I/O |
19//! | **Codec** | [`codec`] | JSON ↔ Rust; [`ServerMessage`] → [`ServerEvent`] decomposition |
20//! | **Audio** | [`audio`] | PCM encoding utilities and format constants |
21//! | **Types** | [`types`] | Strongly-typed wire-format structs |
22//! | **Errors** | [`error`] | Layered error enums |
23//!
24//! ## Quick start
25//!
26//! ```rust,no_run
27//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
28//! use gemini_live::session::{Session, SessionConfig, ReconnectPolicy};
29//! use gemini_live::transport::{Auth, TransportConfig};
30//! use gemini_live::types::*;
31//!
32//! let mut session = Session::connect(SessionConfig {
33//! transport: TransportConfig {
34//! auth: Auth::ApiKey(std::env::var("GEMINI_API_KEY")?),
35//! ..Default::default()
36//! },
37//! setup: SetupConfig {
38//! model: "models/gemini-3.1-flash-live-preview".into(),
39//! generation_config: Some(GenerationConfig {
40//! response_modalities: Some(vec![Modality::Text]),
41//! ..Default::default()
42//! }),
43//! ..Default::default()
44//! },
45//! reconnect: ReconnectPolicy::default(),
46//! }).await?;
47//!
48//! session.send_text("Hello!").await?;
49//!
50//! while let Some(event) = session.next_event().await {
51//! match event {
52//! ServerEvent::ModelText(text) => print!("{text}"),
53//! ServerEvent::TurnComplete => println!("\n--- turn done ---"),
54//! _ => {}
55//! }
56//! }
57//! # Ok(())
58//! # }
59//! ```
60//!
61//! For Vertex AI, switch the transport endpoint and auth mode:
62//!
63//! ```rust,no_run
64//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
65//! use gemini_live::session::{ReconnectPolicy, Session, SessionConfig};
66//! use gemini_live::transport::{Auth, Endpoint, TransportConfig};
67//! use gemini_live::types::*;
68//!
69//! let mut session = Session::connect(SessionConfig {
70//! transport: TransportConfig {
71//! endpoint: Endpoint::VertexAi {
72//! location: "us-central1".into(),
73//! },
74//! auth: Auth::BearerToken(std::env::var("VERTEX_AI_ACCESS_TOKEN")?),
75//! ..Default::default()
76//! },
77//! setup: SetupConfig {
78//! model: std::env::var("VERTEX_MODEL")?,
79//! generation_config: Some(GenerationConfig {
80//! response_modalities: Some(vec![Modality::Text]),
81//! ..Default::default()
82//! }),
83//! ..Default::default()
84//! },
85//! reconnect: ReconnectPolicy::default(),
86//! })
87//! .await?;
88//! # drop(session);
89//! # Ok(())
90//! # }
91//! ```
92//!
93//! Enable the optional `vertex-auth` crate feature if you want the library to
94//! obtain Vertex bearer tokens from Google Cloud Application Default
95//! Credentials instead of passing a static token string.
96
97pub mod audio;
98pub mod codec;
99pub mod error;
100pub mod session;
101pub mod transport;
102pub mod types;
103
104// Re-export the most commonly used items at the crate root for convenience.
105pub use error::*;
106pub use session::{ReconnectPolicy, Session, SessionConfig, SessionStatus};
107#[cfg(feature = "vertex-auth")]
108pub use transport::VertexAiApplicationDefaultCredentials;
109pub use transport::{Auth, BearerTokenProvider, Connection, Endpoint, RawFrame, TransportConfig};
110pub use types::*;