# 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:

```bash
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:

```bash
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:

```yaml
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

1. Start the application and log in when authentication is configured.
2. Choose **Create Task** and upload WAV, MP3, FLAC, or OGG audio.
3. The application writes the upload to `data.upload_directory`, creates a job beneath `jobs.root_directory`, and starts a background transcription process.
4. 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:

```bash
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