Documentation

Everything you need to set up and use AmicoScript.

Overview

AmicoScript is a local-first audio transcription tool powered by Whisper. It provides:

• Audio transcription (Whisper tiny → large-v3)
• Optional speaker diarization
• Transcript management and full-text search
• AI analysis via local LLM (Ollama)
• Export in JSON, SRT, TXT, and Markdown

Quick Start

Docker (Recommended)

docker compose up --build

Then open http://localhost:8002.

Production deployment with HTTPS (Traefik)

cp .env.example .env
# Edit .env: set APP_DOMAIN, TRAEFIK_NETWORK, TRAEFIK_CERTRESOLVER
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

docker-compose.prod.yml adds Traefik labels and joins the Traefik Docker network. TLS termination and Let's Encrypt certificates are handled automatically.

Local Python

pip install -r backend/requirements.txt
python run.py

Requires Python 3.10+. ffmpeg is downloaded automatically on first run.

Desktop App

Download the standalone app from the Releases page — no Python required.

macOS unsigned app: After downloading, go to System Settings → Privacy & Security and click "Open Anyway" to allow the unidentified developer app to run.

Speaker Diarization

Speaker diarization identifies who said what. It uses pyannote and requires a Hugging Face token.

1. Create a free account at huggingface.co
2. Accept the model licenses for pyannote speaker diarization models
3. Generate a hf_ access token in your HF settings
4. Paste the token in AmicoScript's Settings panel

AI Analysis & LLM Integration

AmicoScript can call a locally hosted LLM to produce higher-level analyses from transcripts.

Supported analysis types:

• Summary — concise meeting summary highlighting topics and decisions
• Action items — extracted tasks, owners, and deadlines
• Translation — translate the full transcript via LLM
• Custom prompt — run arbitrary instructions against the transcript

Setting up Ollama

macOS / Windows: Download from ollama.com and run the installer. Ollama starts as a background service automatically.

Linux:

curl -fsSL https://ollama.ai/install.sh | sh
ollama serve

Pull a model

ollama pull mistral       # Fast, good for summaries
ollama pull neural-chat   # Smaller, lighter weight
ollama pull llama2        # More capable (~4 GB)

Configure AmicoScript

1. Open AmicoScript → LLM Settings (sidebar)
2. Set Base URL: http://localhost:11434
3. Set Model Name: your chosen model (e.g., mistral)
4. Click Test Connection

Docker note: If running AmicoScript in Docker and Ollama on your host, use http://host.docker.internal:11434 as the base URL.

GPU Support

To enable GPU acceleration:

1. Use a CUDA-enabled PyTorch base image
2. Update the Dockerfile accordingly
3. Enable GPU support in docker-compose

Performance scales with model size and hardware. Larger models = better accuracy; smaller = faster.

Using the API

Everything the UI does goes through the same HTTP API, so anything you can click you can also script. The full endpoint-by-endpoint reference lives on its own page — it is generated from the server's OpenAPI schema, so it always matches the code rather than drifting from it.

Open the API reference →

The schema itself is at openapi.json if you would rather generate a client. A running install also serves its own interactive copy at http://localhost:8002/docs, and the raw schema at /openapi.json.

Authentication

AmicoScript is local-first, so a request from the machine itself (127.0.0.1, ::1) needs no credentials in the default auto mode. Anything arriving from elsewhere — a reverse proxy, another host on your network — must authenticate:

• Browsers use the session cookie set by POST /api/auth/login.
• Scripts send the API token: Authorization: Bearer <token>.

Fetch the token from the machine itself with GET /api/auth/api-token, or copy it from the app's Security settings. Until a password is set, non-loopback requests are refused with 503 — exposing the app fails closed instead of publishing your library.

curl -H "Authorization: Bearer $AMICOSCRIPT_TOKEN" \
  https://amicoscript.example.com/api/library

Transcribe a file end to end

# 1. start a job — returns {"job_id": "..."}
JOB=$(curl -s -F file=@meeting.m4a -F model=small -F diarize=true \
  http://localhost:8002/api/transcribe | python -c 'import json,sys;print(json.load(sys.stdin)["job_id"])')

# 2. follow progress (Server-Sent Events, one JSON event per update)
curl -N http://localhost:8002/api/jobs/$JOB/stream

# 3. take the result, or an export in json / srt / txt / md
curl http://localhost:8002/api/jobs/$JOB/result
curl -OJ http://localhost:8002/api/jobs/$JOB/export/md

POST /api/transcribe/url takes a url field instead of a file for YouTube, Vimeo and the other supported sources. Jobs can be cancelled with POST /api/jobs/{job_id}/cancel.

Library and search

Finished jobs become recordings: GET /api/library lists them, GET /api/recordings/{id}/transcript returns the segments, and GET /api/search?q=… runs full-text search across every transcript. Speaker names, segment text, folders and tags are all editable over the API too.

Analyses

curl -X POST "http://localhost:8002/api/recordings/<RECORDING_ID>/analyses" \
  -F analysis_type=summary \
  -F output_language=English

curl -X POST "http://localhost:8002/api/llm/test-connection"

Results are polled or fetched with GET /api/recordings/{id}/analyses. LLM configuration lives under /api/llm/settings.