100 lines
5.1 KiB
Markdown
100 lines
5.1 KiB
Markdown
# 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
|