Crate zello_client

Expand description

</– SPDX-License-Identifier: MIT OR Apache-2.0 SPDX-FileCopyrightText: 2024 John C. Murray –>

§Zello Rust Client

A Rust client library for interacting with the Zello API, supporting WebSocket connections for real-time push-to-talk (PTT) communication.

§Features

WebSocket-based connection to Zello channels
Authentication and session management
Send and receive text messages
Audio streaming support (send/receive voice messages)
Async/await support using Tokio
Type-safe message handling
Comprehensive error handling

§Installation

Add this to your Cargo.toml:

[dependencies]
zello-client = "0.2.11"
tokio = { version = "1.48", features = ["full"] }

§Prerequisites

It works on Ubuntu and other Linux distributions with the following audio library dependencies:

pulseaudio-utils,
libopus-dev, and
libasound2-dev packages.

These are the steps to install these required dependencies on distributions that use apt:

sudo apt install pulseaudio-utils
sudo apt install libopus-dev pkg-config
sudo apt install libasound2-dev pkg-config

§Quick Start

You need to set up the required credentials for running an application. Example applications are shown below.

§Authentication

Information must be provided to this command in the form of a .env file with the following variables:

ZELLO_USERNAME='your_username'
ZELLO_PASSWORD='your_password'
ZELLO_TOKEN='your Zello authentication token'
ZELLO_CHANNEL='name of a Zello channel'

The authentication token is required because this application is using a development API which requires this token.

This requirement may change in the future when this Zello API is made public.

§Examples

A simple example showing basic Zello client connection
A more complete example

Ensure you provide a .env file with your credentials.

§Simple Example

You should add the following dependencies to your project’s Cargo.toml:

[dependencies]
anyhow = "1.0.100"
tokio = "1.48.0"
zello-client = "0.2.11"

With the following code in your project’s src/main.rs to run this simple example:

use anyhow::Result;
use zello_client::{
    connect_to_zello, initialize_logging, load_credentials, utilities::load_dotenv,
};

#[tokio::main]
async fn main() -> Result<()> {
    load_dotenv()?;
    initialize_logging()?;
    let credentials = load_credentials()?;
    let mut client = connect_to_zello(&credentials).await?;
    client.send_text_message("Hello from Zello!").await?;
    client.close().await?;
    Ok(())
}

§A more complete example

You should add the following dependencies to your project’s Cargo.toml:

[dependencies]
anyhow = "1.0.100"
clap = "4.5.53"
crossbeam-channel = "0.5.15"
tokio = "1.48.0"
zello-client = "0.2.11"

With the following code in your project’s src/main.rs to run this simple example:

use anyhow::Result;
use clap::Parser;
use crossbeam_channel::bounded;
use std::sync::Arc;
use tokio::sync::Mutex;
use zello_client::{
    PCM_CHANNEL_CAPACITY, connect_to_zello, create_decoder, initialize_logging, load_credentials,
    setup_audio_output, utilities::load_dotenv,
};

#[derive(Parser, Debug)]
#[command(name = "zello-client")]
#[command(about = "This is a simple Zello client application that allows you\n\
to listen to audio messages from and to send text messages to other\n\
users on the Zello platform.")]
#[command(
    long_about = "This is a simple Zello client application that allows you\n\
    to listen to audio messages from and to send text messages to other\n\
    users on the Zello platform.

Information must be provided to this command in the form of\n\
a '.env' file with the following variables:

    ZELLO_USERNAME='your_username'
    ZELLO_PASSWORD='your_password'
    ZELLO_TOKEN='your Zello authentication token'
    ZELLO_CHANNEL='name of a Zello channel'

The authentication token is required because this application\n\
is using a development API which requires this token.\n\
\n\
This requirement may change in the future when the API is made public."
)]
#[command(version = env!("CARGO_PKG_VERSION"))]
struct Args {
    /// Message to send as text message
    #[arg(short = 'm', long)]
    message: Option<String>,

    /// Destination callsign of message (requires --message)
    #[arg(short = 'c', long, requires = "message")]
    callsign: Option<String>,
}

#[tokio::main]
async fn main() -> Result<()> {
    let args = Args::parse();

    load_dotenv()?;
    initialize_logging()?;

    let credentials = load_credentials()?;
    let decoder = create_decoder()?;

    let (pcm_tx, pcm_rx) = bounded::<Vec<i16>>(PCM_CHANNEL_CAPACITY);
    let pcm_rx = Arc::new(Mutex::new(pcm_rx));
    let _stream = setup_audio_output(pcm_rx)?;

    let mut client = connect_to_zello(&credentials).await?;

    match (args.message, args.callsign) {
        (Some(msg), Some(callsign)) => {
            client
                .send_text_message_to_callsign(&msg, &callsign)
                .await?;
        }
        (Some(msg), None) => {
            client.send_text_message(&msg).await?;
        }
        (None, _) => {
            client.run_message_loop(decoder, &pcm_tx).await?;
        }
    }

    client.close().await?;

    Ok(())
}

Re-exports§

pub use error::Result;
pub use error::ZelloError;
pub use handlers::handle_message;
pub use handlers::process_audio_output;
pub use message::CodecHeader;
pub use message::Error;
pub use message::Event;
pub use message::IncomingMessage;
pub use message::Message;
pub use message::Response;
pub use protocol::Protocol;
pub use utilities::connect_to_zello;
pub use utilities::create_decoder;
pub use utilities::initialize_logging;
pub use utilities::load_credentials;
pub use utilities::load_dotenv;
pub use utilities::setup_audio_output;
pub use client::*;

Modules§

client: Zello client implementation
error: Error types for the Zello client
handlers: Handler functions for Zello client operations
message: Message types for Zello protocol
protocol: Zello protocol implementation
utilities: Utility functions for Zello client operations

Constants§

CPAL_BUFFER_SIZE: Cpal buffer size to match Zello audio stream.
CPAL_CHANNELS: Cpal channels to match Zello audio stream.
CPAL_SAMPLE_RATE: Cpal sample rate to match Zello audio stream.
CPAL_VECTOR_QUEUE_CAPACITY: Cpal vector queue capacity to match Zello audio stream.
GIT_VERSION: GIT version
OPUS_CHANNELS: Zello uses a mono audio stream.
OPUS_SAMPLE_RATE: Zello uses a 16kHz sample rate.
PCM_BUFFER_SIZE: PCM buffer size for Zello audio stream.
PCM_CHANNEL_CAPACITY: PCM buffer capacity for Zello audio stream.
PCM_I16_TO_F32: PCM to cpal conversion factor for PCM to cpal audio stream.
VERSION: Library version
ZELLO_DEFAULT_URL: Default Zello WebSocket URL