AmicoScript
AmicoScript local audio transcription tool.
🌐 Website · ⭐ Star if useful · 💬 Telegram @amicoscript · 📊 Benchmarks · 🐛 Issues welcome
AmicoScript is a privacy-focused, local-first transcription tool built on OpenAI's Whisper models. It allows you to transform audio recordings into structured, searchable transcripts without your data ever leaving your repository or machine. Whether you need speaker identification (diarization), translation, or simple subtitles, AmicoScript provides a fast, free, and secure alternative to cloud services.
AmicoScript is perfect for journalists, researchers, students, or anyone who wants control over their audio data and transcripts. It supports batch processing, multiple export formats, and optional AI analysis features — all running locally on your hardware.
✨ Why AmicoScript
Most transcription tools:
- require uploading your audio to the cloud
- cost money or have limits
- don’t give you control over your data
AmicoScript keeps everything local.
→ Your audio never leaves your machine.
📊 How it compares
| Feature | AmicoScript | Buzz | WhisperX | Whisper WebUI | Insanely Fast Whisper |
|---|---|---|---|---|---|
| Local-only (no cloud) | ✅ | ✅ | ✅ | ✅ | ✅ |
| Speaker diarization | ✅ | ✅ | ✅ | ✅ | ✅ |
| Local LLM integration (Ollama, LM Studio, Unsloth, …) | ✅ | ❌ | ❌ | ❌ | ❌ |
| URL import (7 platforms) | ✅ | YouTube only | ❌ | YouTube only | ❌ |
| Batch processing | ✅ | ✅ | ❌ | ✅ | ✅ |
| Desktop app (no Python needed) | ✅ | ✅ | ❌ | ❌ | ❌ |
| Docker support | ✅ | ❌ | ❌ | ✅ | ❌ |
| Web UI | ✅ | ❌ | ❌ | ✅ | ❌ |
| Library backup / import | ✅ | ❌ | ❌ | ❌ | ❌ |
Comparison based on official READMEs as of April 2026. See something wrong? Open a PR.
🚀 Features
- 🎧 Transcribe audio and video (MP3, WAV, M4A, OGG, FLAC, AAC, MP4, MOV, MKV)
- 🎙️ Record directly from your microphone (with pause support)
- 📞 Auto-record meetings (Windows, macOS, Linux — beta) — detects Teams/Zoom/Meet/WhatsApp calls and transcribes them automatically
- 🔗 Import directly from video URLs (YouTube, TikTok, Instagram, Facebook, X, Vimeo, Twitch)
- 📚 Batch process multiple files at once
- 🧠 Whisper models (tiny → large-v3)
- 🤖 AI analysis (summary, action items, translation, custom prompts) — long recordings are summarised in parts and merged, never silently truncated
- ✨ Optional automatic summary when a captured meeting ends
- 🧠 LLM integration: pick Ollama, LM Studio, Unsloth Studio, llama.cpp, vLLM, Jan or LocalAI from a list — or let AmicoScript find the one already running. OpenRouter and other hosted providers are supported too, behind an explicit opt-in
- 🗣️ Speaker diarization (who said what)
- 🌍 Real-time translation to English
- 🔍 Command palette (
Ctrl/⌘+K) — one box that searches transcripts, LLM summaries, names, tags and folders at once, and runs any command in the app. A recording appears once, labelled with where it matched - 💬 Ask your library — a question answered from every transcript at once, with citations that open the recording at the second it was said. Works on keyword search out of the box; name an embedding model and it searches by meaning
- 🗂️ Organize with folders and tags
- ✨ Smart tagging — the LLM reads a transcript and proposes tags, reusing the ones your library already has. Nothing is applied until you click it
- 🏷️ Automatic platform tags for URL imports (for example: youtube, tiktok, instagram)
- 📦 Bulk operations: move to folder, assign/remove tags, export, delete selected recordings
- 🖱️ Multi-select with checkboxes, Ctrl+click (toggle), or Shift+click (range select)
- ✏️ Edit individual segments
- 📤 Export to JSON, SRT, WebVTT, TXT, Markdown, CSV — Markdown carries YAML frontmatter (date, duration, speakers, tags, folder, model), so a transcript dropped into Obsidian, Hugo or Jekyll arrives with its properties filled in
- 💾 Export/import your whole library as one file — backup, or move between machines
- 🔐 Password protection for network access (local use stays password-free)
- ⌨️ Keyboard shortcuts for fast navigation
- 🚀 For Mac, Windows, Docker, or local Python
⛔️ Disclaimer
AmicoScript is a personal project and not affiliated with OpenAI. It uses OpenAI's Whisper models, which are open-source, but AmicoScript itself is independently developed. Use at your own risk. I cannot guarantee the security, privacy, or performance of the application. Always review the code and understand how it works before running it on your machine.
⚡ Example
Upload a meeting recording → get a structured, time-stamped transcript you can search, edit, and export.
Paste a supported video URL in the drop area → AmicoScript fetches the audio and starts transcription automatically.
🖥️ Quick Start
Docker (recommended)
docker compose up --build
Then open: http://localhost:8002
The default image is CPU-only. On a machine with an NVIDIA GPU and the Container Toolkit installed, build the CUDA image instead:
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build
Either way the app picks its device itself, and every job logs which one it got — so if the GPU is not being used, the job log says so rather than just running slowly.
Production deployment with HTTPS (Traefik)
If you're running behind a Traefik reverse proxy, use the production override:
cp .env.example .env
# Edit .env and fill in 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. Traefik handles TLS termination and automatic Let's Encrypt certificates.
🔐 Set a password before exposing AmicoScript. Requests from anywhere other than the machine it runs on are refused until one exists — the app fails closed rather than publishing your transcripts. Set
AMICOSCRIPT_PASSWORDin.env, or open the app on the host and use Security → Set password. Local use is unaffected: on a laptop AmicoScript never asks for anything.If something else already guards the app (an SSO proxy, Traefik basic-auth), set
AMICOSCRIPT_AUTH=off. See docs/doc.md.
Local
pip install -r backend/requirements.txt
pip install -r backend/requirements-diarization.txt # optional: speaker labels
python run.py
The second line is PyTorch and pyannote. Skip it and everything except speaker diarization works; from a source checkout nothing is downloaded on your behalf to make up the difference.
run.py opens a native desktop window when pywebview is installed, and falls
back to a system browser tab when it is not. Override with AMICOSCRIPT_UI:
| Value | Behaviour |
|---|---|
window (default) |
Native window — WKWebView on macOS, WebView2 on Windows |
browser |
Serve only, open the default browser |
none |
Serve only, open nothing (same as AMICOSCRIPT_NO_BROWSER=1) |
On Linux the native window needs system WebKitGTK (gir1.2-webkit2-4.1 +
python3-gi); without it the app degrades to a browser tab. See
docs/desktop-shell.md.
Terminal (TUI)
Prefer the keyboard? AmicoScript also ships a terminal interface — same backend, no browser needed.
./tui.sh # macOS/Linux — installs TUI deps on first run, then launches
tui.bat # Windows
See tui/README.md for keybindings and screenshots. The web UI's Help modal also has a one-click "Copy command" for this.
Tests
pytest -q
📦 Install
One command, identical on macOS, Windows and Linux:
uv tool install amicoscript
amicoscript
uv fetches a suitable Python itself, so nothing needs to be installed first.
(Don't have uv? —
pipx install amicoscript works the same way.) To run it once without
installing: uvx amicoscript.
This is the recommended route, and not only for convenience: nothing here is a downloaded application, so neither Gatekeeper nor SmartScreen is involved. The zips below are unsigned and both will object to them.
Speaker diarization is an optional extra, since transcription never needs torch:
uv tool install "amicoscript[diarization]"
On Linux, that pulls PyPI's default torch, which is the CUDA build and
several GB of nvidia-* packages with it. For a CPU-only machine, name the CPU
index — torch comes from there, everything else still comes from PyPI:
uv tool install "amicoscript[diarization]" \
--index https://download.pytorch.org/whl/cpu
Upgrade with uv tool upgrade amicoscript.
🏃🏼 Running from the installer
In the releases page you can download the application for Windows or Mac (Linux is coming). Be careful that the .exe (or. the dmg) might be recognized as suspicious by the OS.
There is one download per platform — no separate CPU and GPU builds. The app checks for an NVIDIA GPU on the machine it is running on and fetches the matching PyTorch runtime the first time a job needs one, which is the first time you ask for speaker diarization, or the first job on a GPU. Transcribing on a CPU-only machine downloads nothing. See docs/runtime-pack.md if you want to pin the choice or work offline.
macOS: Running unsigned apps (Not disabling Gatekeeper)
This applies to the downloaded .app only. uv tool install amicoscript
(above) skips all of it — Gatekeeper gates downloaded applications, and a wheel
installed into your own environment is not one.
- Download the latest release from the Releases page.
- Because the app is not signed by Apple, macOS will initially block it. Open System Settings → Privacy & Security and enable "App Store and identified developers" (allow apps downloaded from App Store and identified developers).
- Unzip the downloaded file. Double-click the application file (
AmicoScript.app). macOS will prevent it from opening because it's from an unidentified developer. - In System Settings → Privacy & Security, click the "Open Anyway" button next to the blocked app, then confirm when prompted to allow the application to run.
- The app will launch normally after confirmation.
run.py will download ffmpeg automatically on first run.
🧪 Performance
Performance depends on your hardware (CPU/GPU) and selected model size.
- Larger models → better accuracy
- Smaller models → faster processing
Run the built-in benchmark from the transcribe sidebar to measure inference speed on your machine (RTF across tiny/small/medium models). Results can be shared to the community — see BENCHMARKS.md for real-world numbers from different hardware.
If performance on your machine is not acceptable and you are fine with releasing a bit of local-first philosophy, take a look at the Google Colab section.
☁️ Optional: Cloud Power (Google Colab)
If you don't have a powerful local GPU, you can offload the heavy transcription workload to Google Colab for free while keeping the application and your file library strictly local. This option is absolutely optional.
- Toggle Cloud Power on in the sidebar.
- Click Open notebook in Colab ↗ — this opens the notebook directly in Google Colab without any manual upload.
- In Colab, go to Runtime > Change runtime type and select T4 GPU.
- Run Cell 1 to install dependencies (~2–4 min).
- Get your free ngrok authtoken, paste it into
NGROK_AUTH_TOKENin Cell 2, then run it.
- Copy the generated
.ngrok-free.appURL and paste it into the Colab Bridge URL field in AmicoScript.
The ngrok URL changes every session — re-paste it each time you restart the notebook.
Your files will now be seamlessly processed on the cloud GPU, but saved and managed exclusively on your local machine!
📞 Optional: Automatic Meeting Recording (beta)
AmicoScript can notice when you are in a call, record it, and hand the audio to the normal transcription queue when the call ends — so a meeting turns into a searchable transcript without you touching anything.
Detection is entirely local: it inspects which processes are holding your speakers and microphone. No meeting APIs, no calendar access, nothing leaves your machine. It recognises dedicated meeting apps (Teams, Zoom, Webex, GoToMeeting, Whereby, RingCentral) whenever they play audio, and catches browser meetings such as Google Meet plus chat-app calls (WhatsApp, Telegram, Signal, Slack, Discord) by spotting any app using your microphone and speakers at the same time.
Turning it on: open the sidebar → Meeting auto-capture → Auto-record meetings. Nothing is ever recorded until you flip that switch.
- Packaged app: the helper is built in. Just use the toggle.
- Docker / running from source: the app cannot reach your host's audio, so a
small background helper is installed separately. A banner offers the right
one-click installer for your system (
setup.bat,setup.commandorsetup.sh). No admin rights needed. See scripts/meeting_watcher/README.md.
| Supported | Needs | |
|---|---|---|
| Windows | ✅ | nothing extra |
| macOS | ✅ | macOS 14.2+, and one permission you must grant by hand — see below |
| Linux | ✅ | pactl/parec (pulseaudio-utils); PulseAudio or PipeWire |
While a meeting is being captured you get a red Recording chip with a live timer in the app, desktop notifications when recording starts and stops, and on Windows a coloured tray icon (right-click to pause). Recordings shorter than 15 seconds are discarded as false triggers. Meetings are transcribed with the same model, language and diarization settings shown in your sidebar.
macOS permission. Recording the computer's audio needs Screen & System Audio Recording consent. When it is missing macOS does not refuse — it hands back a silent recording while reporting success. AmicoScript detects that and says so in the sidebar rather than filing an empty meeting, but you have to grant it yourself in System Settings. The packaged app prompts for it; a watcher started from a terminal or a login agent does not. Details in the watcher README.
⚠️ Recording a conversation may require the consent of everyone involved and may be restricted by your employer's policy or local law. Make sure you are allowed to record before enabling this.
🧩 Optional: Speaker Diarization
Uses pyannote and requires a Hugging Face token.
See full setup instructions in: Documentation
🤖 AI Analysis & LLM
New in 1.4: AmicoScript can call a local LLM to produce analyses from transcripts — summaries, action-item extraction, full translations, or custom-prompt runs. Key notes:
Setting it up: open LLM Settings in the sidebar and either pick your tool from the list — Ollama, LM Studio, Unsloth Studio, llama.cpp, vLLM, Jan, LocalAI, OpenRouter, or anything OpenAI-compatible — or press Find running servers and let AmicoScript scan for one. It fills in the address, tells you whether a key is needed and what it looks like, and offers the models that server already has.
- Paste the address in whatever form your tool showed it.
http://localhost:1234,.../v1and a full.../v1/chat/completionsall work; AmicoScript normalises it and tells you what it changed. - Docker just works. The compose file maps
host.docker.internal, and addresses typed aslocalhostare rewritten to it automatically, with a note explaining why. Your LLM still has to listen beyond loopback (OLLAMA_HOST=0.0.0.0for Ollama, "Serve on Local Network" for LM Studio). - Hosted providers are opt-in. Audio never leaves your machine, but a hosted provider receives the transcript text. OpenRouter and any remote address are gated behind a confirmation, and analyses refuse to run until you give it.
- Test the connection from the UI or via
POST /api/llm/test-connection— failures say which tool is not running, whether the key is wrong, or whether the address has a stray/v1. - Per-recording analyses:
POST /api/recordings/{recording_id}/analyses,GET /api/recordings/{recording_id}/analyses.
See docs/doc.md for the full provider table.
📚 Documentation
Full documentation (API, setup, details):
Documentation · Desktop shell (window, packaging, Tauri roadmap)
API reference — every endpoint the UI uses,
generated from the FastAPI routes with python scripts/generate_openapi.py and published with the
site. A running install serves the same thing at http://localhost:8002/docs.
🏗️ Architecture (brief)
- Backend: Python + FastAPI (
backend/main.py+ modular routers inbackend/api/routes/) - Frontend: plain ES modules in
frontend/js/, loaded natively — still no build step - Processing: downloads run concurrently, model inference stays serialized; interrupted jobs are requeued on restart
- Storage: local SQLite metadata (versioned migrations) + managed recording files, exportable as a single bundle
🗺️ Roadmap
See docs/ROADMAP.md for full priority breakdown.
Currently planned:
- Speaker library — recognise recurring voices across recordings
- Chat with your library (semantic search + Q&A over all transcripts)
- AI-powered smart tagging
🤝 Contributing
Feedback, issues, and contributions are welcome. See CONTRIBUTING.md for how to get started.
⭐ Star & Share
If AmicoScript saves you time, a star helps others discover it.
💬 Join the community on Telegram @amicoscript — share feedback, request features, show what you built.
⚖️ License
This project is licensed under the MIT License. See the LICENSE file for more details.
Metadata
Release files for amicoscript 1.18.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| amicoscript-1.18.1.tar.gz | 24.3 MB | With provenance | Details for amicoscript-1.18.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| amicoscript-1.18.1-py3-none-any.whl | Python 3 | none | any | Details for amicoscript-1.18.1-py3-none-any.whl |
Total release size: 48.5 MB
Release files / amicoscript-1.18.1.tar.gz
| Download URL | amicoscript-1.18.1.tar.gz |
|---|---|
| Size | 24.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0bf7423e63c271c8a2a03bd527d8607331923454aaeb74c9542112c3f6459b6d
|
|
BLAKE2b-256 checksum How to use checksums |
c76b8e69e379066c6a62077a9fc8adb79e7296952bf1bbada9f45c5facc15851
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 15, 2026.
Transparency logRelease files / amicoscript-1.18.1-py3-none-any.whl
| Download URL | amicoscript-1.18.1-py3-none-any.whl |
|---|---|
| Size | 24.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ce7d3f4fd8c250e2eb083084d18d5f5855166834af5e9655913647e2ade73b3a
|
|
BLAKE2b-256 checksum How to use checksums |
81c31eb24235a2177e33f3089cf1b2f9f650072620f126d0394130e012a5d405
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 15, 2026.
Transparency logSecurity for amicoscript 1.18.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for amicoscript-1.18.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.