GladiaPP

A C++ client library for the Gladia audio transcription API. Supports both REST API for pre-recorded audio and WebSocket for real-time transcription.

Note: This is a community project, not officially affiliated with Gladia.

Features

• Audio upload and batch transcription (REST API)
• Real-time transcription (WebSocket)
• Multi-language translation
• Speaker diarization
• Subtitle generation (SRT/VTT)
• Named entity recognition
• Sentiment analysis and summarization
• Asynchronous operations

Requirements

• C++17 or later
• CMake 3.16 or later
• Internet connection for API calls

Dependencies

Dependencies are managed automatically via vcpkg.json:

• curl (SSL, WebSocket features) - HTTP and WebSocket client
• nlohmann/json - JSON parsing
• spdlog - Logging
• base64 - Base64 encoding/decoding (fetched via CMake)

Installation

The project uses vcpkg manifest mode for automatic dependency management.

Build Steps

1. Install vcpkg if you haven't already:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh  # On Windows: .\bootstrap-vcpkg.bat

2. Clone and build the project:

git clone https://github.com/fatehmtd/gladiapp.git
cd gladiapp
mkdir build && cd build

3. Configure with vcpkg (dependencies installed automatically):

# Linux/macOS
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

# Windows
cmake .. -DCMAKE_TOOLCHAIN_FILE=C:\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake

# Optional: Build with examples
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -DBUILD_EXAMPLES=ON

4. Build:

cmake --build .

Manual Dependencies (if not using vcpkg)

If you prefer to install dependencies manually:

• macOS: brew install curl cmake (ensure curl was built with WebSocket support; the Homebrew formula's curl usually is not, so vcpkg is recommended instead)
• Ubuntu/Debian: sudo apt-get install libcurl4-openssl-dev cmake build-essential
• Windows: Use Visual Studio with vcpkg integration, or install dependencies manually

Note: gladiapp uses libcurl's native WebSocket support (curl_ws_*), which requires curl built with the websockets feature enabled. This is off by default in most system package managers, so vcpkg (which builds curl with ssl and websockets features per vcpkg.json) is the recommended path.

Quick Start

REST API (Pre-recorded Audio)

#include "gladiapp/gladiapp_rest.hpp"

int main() {
    gladiapp::v2::GladiaRestClient client("your-api-key");
    
    // Upload audio file
    auto uploadResponse = client.upload("/path/to/audio.wav");
    
    // Create transcription request
    gladiapp::v2::request::TranscriptionRequest request;
    request.audio_url = uploadResponse.audio_url;
    request.diarization = true;
    request.translation = true;
    request.translation_config.target_languages = {"fr", "es"};
    
    // Start transcription
    auto jobResponse = client.preRecorded(request);
    
    // Poll for completion
    while (true) {
        auto result = client.getResult(jobResponse.id);
        if (result.status == "done") break;
        std::this_thread::sleep_for(std::chrono::seconds(5));
    }
    
    return 0;
}

WebSocket (Real-time Audio)

#include "gladiapp/gladiapp_ws.hpp"

using namesapce gladiapp::v2::ws;

int main() {
    GladiaWebsocketClient client("your-api-key");
    
    // Configure session
    request::InitializeSessionRequest initRequest;
    initRequest.channels = 1;
    initRequest.bit_depth = request::InitializeSessionRequest::BitDepth::BIT_DEPTH_16;
    initRequest.encoding = request::InitializeSessionRequest::Encoding::WAV_PCM;
    initRequest.sample_rate = request::InitializeSessionRequest::SampleRate::SAMPLE_RATE_16000;
    
    // Create session
    auto session = client.connect(initRequest);
    if (session && session->connectAndStart()) {
        session->setOnTranscriptCallback([](const auto& transcript) {
            std::cout << transcript.data.utterance.text << std::endl;
        });
        
        // Send audio data
        std::vector<uint8_t> audioData = readAudioFile("audio.wav");
        session->sendAudioBinary(audioData.data(), audioData.size());
        
        session->sendStopSignal();
        session->disconnect();
    }
    
    return 0;
}

API Usage

REST API vs WebSocket

REST API: Use for pre-recorded audio files, batch processing, or when high accuracy is more important than speed.

WebSocket: Use for real-time transcription, live audio streams, or interactive applications requiring immediate feedback.

Examples (Optional)

Working examples are provided in the examples/ directory demonstrating both REST API and WebSocket functionality. Examples are optional and can be built separately from the main library.

Building Examples

To build the examples, enable the BUILD_EXAMPLES option:

mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -DBUILD_EXAMPLES=ON
cmake --build .
cmake --install . --prefix ./install

API Key Setup

The examples use dotenv-cpp for secure API key management.

Option 1: Environment Variable

# Windows PowerShell
$env:GLADIA_API_KEY="your-api-key"

# Linux/macOS
export GLADIA_API_KEY="your-api-key"

Option 2: .env File

Create a .env file in the project root:

GLADIA_API_KEY=your-api-key

See API_KEY_SETUP.md for detailed instructions.

API Reference

GladiaRestClient

GladiaRestClient(const std::string& apiKey, const std::string& caFilePath = {});

// Upload audio file
UploadResponse upload(const std::string& filePath, TranscriptionError* error = nullptr);

// Create transcription job
PreRecordedResponse preRecorded(const TranscriptionRequest& request, TranscriptionError* error = nullptr);

// Get transcription result
ResultResponse getResult(const std::string& id, TranscriptionError* error = nullptr);

// List all results
ListResultsResponse getResults(const ListResultsQuery& query, TranscriptionError* error = nullptr);

// Delete a result
void deleteResult(const std::string& id, TranscriptionError* error = nullptr);

GladiaWebsocketClient

GladiaWebsocketClient(const std::string& apiKey, const std::string& caFilePath = {});

// Create WebSocket session
std::shared_ptr<Session> connect(const InitializeSessionRequest& request, TranscriptionError* error = nullptr);

// Session methods
bool connectAndStart();
void sendAudioBinary(const uint8_t* data, int size);
void sendStopSignal();
void disconnect();

// Event callbacks
void setOnTranscriptCallback(std::function<void(const TranscriptResponse&)>);
void setOnTranslationCallback(std::function<void(const TranslationResponse&)>);
// ... other callbacks

Configuration

TranscriptionRequest: diarization, translation, subtitles, sentences, named_entity_recognition, sentiment_analysis, summarization, custom_vocabulary, custom_spelling, audio_to_llm, pii_redaction, punctuation_enhanced, custom_metadata

InitializeSessionRequest: Audio format settings (channels, bit_depth, encoding, sample_rate), real-time processing options, post-processing settings

Project Structure

gladiapp/
├── CMakeLists.txt
├── README.md
├── LICENSE
├── vcpkg.json                 # Dependency manifest
├── examples/                  # Optional examples (BUILD_EXAMPLES=ON)
│   ├── common/
│   │   └── apiKeyLoader.hpp   # API key management
│   ├── example-rest/          # REST API example
│   └── example-ws/            # WebSocket example
└── gladiapp/                  # Main library
    ├── include/gladiapp/      # Public headers
    └── src/                   # Implementation

Contributing

Contributions are welcome! This is a community-driven project.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -m 'Add new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Open a Pull Request

Guidelines

• Follow modern C++ practices (C++17+)
• Add tests for new features
• Update documentation as needed
• Ensure code compiles without warnings

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: Check header files for API details
• Issues: Report bugs via GitHub Issues
• Discussions: Join community discussions via GitHub Discussions

---

Note: This project is not affiliated with Gladia. It is an independent, community-driven client library.