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.

API Reference

Models

GET /api/models — Returns available Whisper models.

Settings

GET /api/settings — Retrieve saved settings (HF token, LLM config).

POST /api/settings — Save settings.

Transcription

POST /api/transcribe — Upload an audio file and start a transcription job.

// Response
{
  "job_id": "string"
}

Jobs

GET /api/jobs/{id}/stream — Server-Sent Events stream for real-time progress.

POST /api/jobs/{id}/cancel — Cancel a running job.

GET /api/jobs/{id}/result — Full transcription result as JSON.

Export

GET /api/jobs/{id}/export/{fmt} — Download transcript in json, srt, txt, or md format.

LLM

GET /api/llm/settings — Current LLM configuration.

POST /api/llm/settings — Save LLM settings (llm_base_url, llm_model_name, llm_api_key).

POST /api/llm/test-connection — Quick connectivity test.

GET /api/llm/models — List models exposed by the LLM server.

POST /api/llm/models/pull — Trigger model pull (Ollama-style).

POST /api/recordings/{id}/analyses — Create a new analysis job.

GET /api/recordings/{id}/analyses — List past analyses for a recording.

GET /api/recordings/{id}/analyses/{analysis_id} — Fetch a specific analysis result.

Example: start an analysis

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

Example: test LLM connection

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