# AudioIngress
`kcode-audio-ingress` is a standalone Rust library for durable, automatic
audio transcription. It accepts a complete owned audio buffer, persists the
original before returning, transcribes overlapping audio pieces, durably
persists every completed piece transcript, reconciles them, and persists the
canonical transcript.
It is not an HTTP service. Multipart parsing, upload-size policy, browser
responses, transcript splitting, and delivery into Kennedy memory belong to
the embedding application.
Every recording has a non-empty stable application user identifier.
`AudioTranscriber` makes model requests only through caller-supplied typed
structured-audio and text-generation callbacks. Those requests include the
stable user and exact model; provider routing, metering, and durable accounting
belong to the embedding intelligence component.
## Public API
The intentionally small surface is:
```rust
let ingress = AudioIngress::open(persistence_root, transcriber).await?;
let submitted = ingress.submit(AudioInput {
user_id,
bytes,
recorded_at,
original_filename,
}).await?;
let status = ingress.status()?;
ingress.retry(recording_id)?;
```
- `open` accepts one persistence-root path and an `AudioTranscriber`.
- `submit` accepts a stable user ID, one `Vec<u8>`, the recording time, and an
optional original filename. It returns only after the original and job
record are durable.
- `status` returns all recording identities, metadata, processing progress,
completed transcripts, and failures.
- `retry` requeues one failed recording after a caller has decided that the
external problem was corrected.
Callers do not drive individual processing stages. Opening and submitting wake
the library's background worker automatically.
## Persistence and identity
AudioIngress owns everything below its configured root:
```text
<root>/
state.sqlite3
originals/
```
Originals are content-addressed by SHA-256. Submitting identical bytes is
idempotent even when the filename changes. The library has no storage quota and
does not remove originals; an embedding application may reject an input before
submission or manage deployment-level capacity outside the library.
There is no streaming submission API. The transcription pipeline requires the
complete audio in memory, so retaining a second streaming abstraction would
only complicate the boundary without reducing the peak memory requirement.
SQLite stores recording metadata, durable progress, the canonical transcript,
and every validated structured piece transcript. Piece rows include the
recording identifier, full-job attempt, chronological index, piece count, and
source-audio interval. A piece is committed before its processing step is
reported complete. Attempts are retained separately rather than overwriting
one another.
## Processing and retries
The durable public states are queued, processing, complete, and failed.
Processing progress is the typed `TranscriptionStatus` with any transcript
body removed; the canonical transcript appears only in the complete state.
AudioIngress automatically retries a retryable full-job failure up to five
times, with a short fixed delay between attempts. A structurally invalid input
or another non-retryable dependency failure stops immediately. Once automatic
attempts are exhausted, no further work occurs until `retry` resets the
five-attempt budget. Retry policy is deliberately not configurable.
An active transcription job exists only in memory. If the process stops, the
accepted original, completed piece transcripts, and latest durable progress
remain, and opening the library starts a fresh attempt from the original bytes.
## Integrated transcription pipeline
The same crate owns audio validation, working-audio preparation, chunk
planning, per-step progress, piece persistence, and transcript reconciliation.
The `AudioTranscriber` in-memory job API remains public for callers that need
it, while `AudioIngress` installs the internal durable-piece sink. No provider
client or credential is constructed internally.
## Boundary with KennedyServer
KennedyServer owns:
- Axum routes and multipart parsing;
- upload-size limits and other deployment policy;
- conversion of library status into browser-facing JSON;
- splitting completed transcripts for Kennedy memory ingress;
- downstream claims, checkpoints, retries, failures, and completion;
- the global Kweb writer lane.
Consequently no Axum, HTTP, `OpaquePiece`, delivery-failure, streaming, or
Kennedy/Kweb type appears in the standalone library API.
## Managed-library packaging
The crate is conforming source for `kcode-rust-libs-v2`. Its root manifest has
literal standalone package metadata and explicit dependency requirements.
`Documentation.md` is the complete agent-facing API reference. Generated
`Cargo.lock` and build artifacts are not managed package source.