Installation¶

audio-transcriber is a standard Python package and a prebuilt container image. Pick the path that matches how the operator want to run it.

Requirements¶

Python 3.11 – 3.14.
ffmpeg for broad audio-format support, and the PortAudio system libraries for microphone recording. On Debian / Ubuntu:

sudo apt-get update
sudo apt-get install -y libasound-dev portaudio19-dev libportaudio2 \
  libportaudiocpp0 ffmpeg gcc

Then, only for microphone recording: pip install "audio-transcriber[microphone]". The microphone extra installs pyaudio, which compiles against PortAudio, so it needs the system libraries above. File transcription and the MCP server do not need it.

The Whisper model is loaded locally; no external transcription service is required.

From PyPI (recommended)¶

pip install audio-transcriber

Optional extras¶

The base install ships the CLI and the faster-whisper backend. Install the extra for the interface the operator need:

Extra	Install	Pulls in
`mcp`	`pip install "audio-transcriber[mcp]"`	FastMCP MCP-server runtime (`scion-sdk`) + `websockets`
`local`	`pip install "audio-transcriber[local]"`	`openai-whisper` reference backend (fallback to `faster-whisper`)
`all`	`pip install "audio-transcriber[all]"`	The `mcp` and `agent` extras together

From source¶

git clone https://github.com/Knuckles-Team/audio-transcriber.git
cd audio-transcriber
pip install -e ".[all]"          # editable install with every extra

With uv:

uv pip install -e ".[all]"
uv run audio-transcriber-mcp

Prebuilt Docker image¶

A MCP-serving image is published on every release (entrypoint audio-transcriber-mcp):

docker pull example/audio-transcriber@sha256:<digest>

docker run --rm -i \
  -e WHISPER_MODEL=base \
  example/audio-transcriber@sha256:<digest>        # stdio transport (default)

For an HTTP server with a published port, see Deployment.

Verify the install¶

audio-transcriber --help
audio-transcriber-mcp --help
python -c "import audio_transcriber; print(audio_transcriber.__version__)"

Next steps¶

Deployment — run it as a long-lived MCP server and agent behind Caddy + DNS.
Usage — call the tool, the API, and the CLI.
Configuration — every environment variable.