AnneScribe

AnneScribe is a Streamlit web application for creating and monitoring filesystem-backed audio-transcription jobs. Users upload WAV, MP3, FLAC, or OGG audio; the application splits the audio and transcribes chunks with Whisper, then writes a combined output.txt for each job.

Status and important limitations

This is an early, filesystem-backed application rather than a production-ready transcription service.

The application has no tracked authentication example. Although a missing AUTH_FILE disables the authentication setup, the current home page still calls the authenticator's logout method unconditionally; the unauthenticated path is therefore not a supported runnable mode. Treat an absent auth file as unsafe for exposed deployments.
auth.yml is ignored by Git. Create it locally from the configuration shape required by streamlit-authenticator; do not commit credentials, cookie keys, or other private settings.
The checked-in config.yml selects cuda. A working CUDA/PyTorch setup is needed for that configuration; a CPU configuration must set the model device accordingly.
Jobs and uploads are stored on the filesystem. The included Compose configuration does not declare a persistent volume for those directories, so container recreation can lose job data.
The task list does not automatically refresh; use the UI refresh control.
No project test suite or test command is defined. GitLab CI includes only the SAST template.

Prerequisites

Python 3.10.16 for local installation (the project requires exactly this version).
FFmpeg for local audio conversion and splitting. The supplied Dockerfile installs it.
A Python environment capable of installing the dependencies declared in pyproject.toml, including PyTorch, OpenAI Whisper, Streamlit, and pydub.
A writable location for uploads and job data.

Local setup and run

From the repository root, install the package:

python -m pip install .

Copy or create a local application configuration. The tracked config.yml is a starting point for non-secret settings. Set the paths and model device for the environment, and create a private auth.yml if authentication is required.

Run the Streamlit entry point from the repository root:

streamlit run src/annescribe/webapp_main.py

The repository does not define a separate development server, test, lint, or format command.

Configuration

The application reads these environment variables:

Variable	Default	Purpose
`CONFIG_FILE`	`config.yml`	YAML application configuration path
`AUTH_FILE`	`auth.yml`	YAML authentication configuration path; if missing, authentication is disabled

CONFIG_FILE must exist. Its YAML is read for:

jobs:
  root_directory: ./jobs
data:
  upload_directory: ./uploads
audio:
  chunking:
    min_silence_level: -30
    min_silence_length: 400
    ms_silence_to_keep: 50
model:
  type: large
  device: cuda

Use paths appropriate for the process working directory. model.type is passed to Whisper, and model.device is used to move the loaded model.

When present, the authentication YAML must provide the credentials and cookie objects read by streamlit-authenticator; the code reads cookie.name, cookie.key, and cookie.expiry_days. Keep this file private.

Using the UI

Start the application and log in when authentication is configured.
Choose Create Task and upload WAV, MP3, FLAC, or OGG audio.
The application writes the upload to data.upload_directory, creates a job beneath jobs.root_directory, and starts a background transcription process.
Use the task list to view progress and completed output. A job name is derived from the uploaded filename; choose the overwrite option to rerun a job with the same name.

Security warning: uploaded filenames reach shell-based processing. Run this UI only for trusted, authenticated users and filenames, and do not place it behind an unauthenticated upload proxy.

Container operation

The repository supplies a Dockerfile and Compose file. From the repository root, build and start it with:

docker compose up --build

The Compose service exposes port 8501, mounts local config.yml and auth.yml into /app, and expects an existing external Docker network named web. It also contains Traefik labels, so its proxy configuration assumes a compatible Traefik environment. Create and secure the external network and the private auth.yml before using this configuration.

The image starts the same Streamlit entry point. No deployment automation or production persistence configuration is defined beyond this Compose file.

Repository layout

src/annescribe/webapp_main.py — Streamlit entry point and configuration/authentication loading
src/annescribe/webapp/ — home page, task list, and upload UI
src/annescribe/transcription/ — audio conversion, splitting, job handling, and Whisper transcription
config.yml — tracked non-secret application configuration
Dockerfile, docker-compose.yml — container build and local Compose configuration
pyproject.toml — Python package metadata and runtime dependencies

5.1 KiB Raw Blame History