Sturnus

Discord voice transcription with Outline document output.

A guild names the voice channels Sturnus is allowed to record in, and Sturnus joins whichever of them is meeting: it records each participant's audio into a separate stream for the duration of the session, and — once the session ends — transcribes each stream with faster-whisper and assembles the results into a single chronological protocol, posted as a document in Outline and linked back into the channel's text chat. A Discord bot holds one voice connection per guild, so a list of allowed channels means "any of these, one at a time" rather than "all of these at once"; when two of them are busy, the one with the most consenting members wins and the other waits.

Nobody may be recorded without consent: every recording channel denies Speak to @everyone and allows it only for a role granted through /consent, and the bot additionally drops any audio packet from a user who does not hold that role, even if Discord permissions alone would have let it through (guild administrators bypass channel overwrites). See docs/operations.md for why a non-recorded channel must also exist alongside them.

Recordings are encrypted at rest — in the object store and for the whole retention window, which exists so a poor transcription can be reprocessed — and are deleted when it expires. Transcription itself happens elsewhere: at the moment a recording is transcribed, a chunk of plaintext audio is sent over TLS to the OpenAI-compatible endpoint the operator configured, which may be OpenAI's, a self-hosted vLLM, or anything else speaking the same interface. Which host that is has no default, is named in /about, and is named in the /consent prompt before anybody agrees to be recorded. See docs/operations.md for what all of this means operationally, including what happens if the encryption key is lost.

Running locally

Requires Python 3.12+ and uv.

uv sync

The bot needs a PostgreSQL database, an S3-compatible object store, and an OpenAI-compatible /audio/transcriptions endpoint reachable before it can start; point it at them (and everything else it needs) through environment variables — see docs/operations.md for the full list. STURNUS_TRANSCRIPTION_BASE_URL has no default on purpose: a process without it refuses to start rather than sending audio somewhere nobody chose. With those set:

uv run sturnus-bot     # Discord gateway connection + recording
uv run sturnus-worker  # transcription + document publishing
uv run sturnus-link    # OAuth account-link callback

Deploying to a cluster for the first time needs several things nobody can generate for you — a Discord application, two Outline credentials, an encryption key whose loss is unrecoverable. docs/first-deployment.md is the checklist, in the order the steps actually depend on each other.

Run the checks the same way CI does:

uv run pytest
uv run mypy
uv run ruff check

License

Sturnus is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE for the full text. The AGPL was chosen deliberately because Sturnus is a self-hosted network service: anyone interacting with a modified deployment over Discord is entitled, under section 13 of the license, to receive that deployment's corresponding source. The bot's /about command exists to make that offer directly to users.

Documentation

• docs/operations.md — environment variables, the master key and what its loss means, Discord setup, first run, troubleshooting, retention.
• docs/superpowers/specs/2026-08-19-sturnus-design.md — full design document.