docling-gigaam

docling-gigaam adds Russian speech recognition through GigaAM v3 to Docling 2.121 without forking Docling. It provides standalone transcription plus custom audio and video pipelines. Video conversion keeps Docling's inherited frame sampling, scene detection, diarization, sentence merge, and timestamp merge.

Install

Python 3.11 or newer and the system ffmpeg executable are required.

pip install docling-gigaam

On first transcription, the official GigaAM model host downloads approximately 450 MB of model weights plus the tokenizer into docling-gigaam/ under the selected cache root. HF_HUB_CACHE and HF_HOME are honored by default. Set cache_dir to use another root, or local_files_only=True after prefetching.

Standalone Usage

from docling_gigaam import GigaAmTranscriber

segments = GigaAmTranscriber().transcribe("recording.mp3")
for segment in segments:
    print(segment.start_time, segment.end_time, segment.text)

Audio at or below 25 seconds uses the short path. Longer audio is decoded to mono 16 kHz, segmented with Silero VAD, merged into model-sized chunks, and processed in batches. Returned segment timestamps are absolute offsets from the start of the source. Word timestamps are not provided in version 0.1.

Audio With Docling

from docling.datamodel.base_models import InputFormat
from docling.document_converter import DocumentConverter
from docling_gigaam import audio_format_option

converter = DocumentConverter(
    allowed_formats=[InputFormat.AUDIO],
    format_options={InputFormat.AUDIO: audio_format_option()},
)
result = converter.convert("recording.mp3")
print(result.document.export_to_markdown())

Each transcript segment is a Docling text item with a public TrackSource containing its absolute start and end time.

Video With Docling

from docling.datamodel.base_models import InputFormat
from docling.document_converter import DocumentConverter
from docling_gigaam import GigaAmVideoPipelineOptions, video_format_option

options = GigaAmVideoPipelineOptions(
    generate_frame_images=True,
    frame_interval_seconds=10.0,
)
converter = DocumentConverter(
    allowed_formats=[InputFormat.VIDEO],
    format_options={InputFormat.VIDEO: video_format_option(options)},
)
result = converter.convert("meeting.mp4")
print(result.document.export_to_markdown())

Model And Security

The package vendors the official MIT-licensed GigaAM inference runtime from commit 7447938d791c4f3e643386ee22c33777004293a5. It does not execute Hugging Face remote code and does not depend on the stale gigaam==0.1.0 PyPI release.

Model weights are not included in the wheel. The official v3_e2e_rnnt checkpoint and tokenizer are downloaded lazily from the GigaAM project host. The upstream MD5 checksum is verified before the checkpoint is loaded, so a silently replaced model is rejected.

GigaAM v3 is intended for Russian speech. Accuracy for other languages is not a supported scope of this package.

Devices

device="auto" selects CUDA, then Apple MPS, then CPU. MPS is not tested by GigaAM upstream and emits a warning. If MPS encounters unsupported operations, set PYTORCH_ENABLE_MPS_FALLBACK=1 or select CPU explicitly.

Attribution

The pure Silero interval-merging logic in docling_gigaam.vad is adapted from the MIT-licensed SmetDenis/gigaam-openai-api-server, which in turn follows GigaAM's long-form VAD merge design. This package adapts only the focused chunking approach and does not copy the unrelated API server. The GigaAM inference runtime and its license are recorded in THIRD_PARTY_NOTICES.md.

Development

uv sync --extra dev
uv run pytest -m "not integration"
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv build

The integration scaffold is opt-in because it downloads the model:

DOCLING_GIGAAM_RUN_INTEGRATION=1 \
DOCLING_GIGAAM_SAMPLE=/path/to/russian.wav \
uv run pytest -m integration