Biblicus

Make your documents usable by your assistant, then decide later how you will search and retrieve them.

Aldea Speech-to-Text Extractor

Extractor ID: stt-aldea

Category: Speech-to-Text Extractors

Overview

The Aldea speech-to-text extractor uses the Aldea Speech-to-Text API to transcribe audio files. The API supports pre-recorded audio via REST and returns Deepgram-compatible response shapes (channels, alternatives, transcript). You can use the optional deepgram-transform stage after stt-aldea to render words or utterances when timestamps or diarization are enabled.

Installation

Install the optional Aldea dependency (httpx):

pip install "biblicus[aldea]"

You'll also need an Aldea API key (tokens start with org_).

Supported Media Types

Only audio items are processed. Other media types are automatically skipped.

Configuration

Config Schema

class AldeaSpeechToTextExtractorConfig(BaseModel):
    language: Optional[str] = None   # BCP-47 (e.g. en-US, es)
    diarization: bool = False
    timestamps: bool = False

Configuration Options

Option Type Default Description
language str or null null Language code hint in BCP-47 format (e.g. en-US, es)
diarization bool false Enable speaker diarization (requires word timestamps)
timestamps bool false Include per-word timestamps in the response

Usage

Command Line

Basic Usage

# Configure API key
export ALDEA_API_KEY="your-key-here"

# Extract audio transcripts
biblicus extract my-corpus --extractor stt-aldea

Custom Configuration

# Enable language hint and timestamps
biblicus extract my-corpus --extractor stt-aldea \
  --config language=en-US,timestamps=true

# Enable speaker diarization
biblicus extract my-corpus --extractor stt-aldea \
  --config diarization=true

Configuration File

extractor_id: stt-aldea
config:
  language: null
  diarization: false
  timestamps: false
biblicus extract my-corpus --configuration configuration.yml

Python API

from biblicus import Corpus
from biblicus.extractors import get_extractor

corpus = Corpus.from_directory("my-corpus")
extractor = get_extractor("stt-aldea")
config = extractor.validate_config({})
# Then use in your extraction pipeline

Authentication

Set your Aldea API key via environment or user config. Environment takes precedence.

Environment Variable

export ALDEA_API_KEY="org_your_api_key_here"

Configuration File

Add to ~/.biblicus/config.yml or ./.biblicus/config.yml:

aldea:
  api_key: org_your_api_key_here

See User configuration for details.

Response and Metadata

The extractor stores the full Aldea API response in stage metadata under the key aldea. The structure matches the Pre-Recorded Audio API: metadata (request_id, duration, channels) and results.channels[].alternatives[].transcript (and optionally words when timestamps are enabled). You can use deepgram-transform in a pipeline after stt-aldea to render words or utterances from this metadata.

Error Handling

See Also