From 9c8461405fe4d8fb9117cda35e64475559d4e4b0 Mon Sep 17 00:00:00 2001
From: Ben <ben@kraal.se>
Date: Wed, 12 Aug 2026 13:58:56 +0200
Subject: [PATCH] Document AndyTranscribe setup and transcription engines.

---
 README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..65924b8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,110 @@
+# AndyTranscribe
+
+Upload pocket-recorder MP3s, extract ID3 metadata, and transcribe them with OpenAI Whisper, a local faster-whisper server, or a remote OpenAI-compatible endpoint.
+
+Built with Laravel 13, Blade, Tailwind CSS 4, and [Laravel AI](https://github.com/laravel/ai).
+
+## Features
+
+- Upload MP3s (up to 100 MB) and store them on the local disk
+- Automatic ID3 metadata extraction (title, artist, album, duration, recorded date)
+- Search recordings by title, artist, or transcript
+- Queued transcription with three engines:
+  - **Cloud** — OpenAI Whisper (`whisper-1`)
+  - **Local** — confidential; OpenAI-compatible [faster-whisper-server](https://github.com/fedirz/faster-whisper-server) (e.g. Docker on this machine)
+  - **Ollama host** — user-supplied host URL exposing `/v1/audio/transcriptions`
+- Copy finished transcripts from the recording detail page
+
+## Requirements
+
+- PHP 8.3+ (8.5 recommended)
+- Composer
+- Node.js & npm
+- SQLite (default) or another supported database
+- For cloud transcription: an OpenAI API key
+- For local transcription: a running faster-whisper-server
+- For remote transcription: a host with an OpenAI-compatible transcription API
+
+## Setup
+
+```bash
+composer setup
+```
+
+That installs PHP and JS dependencies, copies `.env` if needed, generates the app key, runs migrations, and builds frontend assets.
+
+Or step by step:
+
+```bash
+composer install
+cp .env.example .env
+php artisan key:generate
+touch database/database.sqlite   # if using SQLite
+php artisan migrate
+npm install
+npm run build
+```
+
+## Configuration
+
+Copy values from `.env.example`. The transcription-related settings are:
+
+| Variable | Purpose |
+| --- | --- |
+| `OPENAI_API_KEY` | Required for cloud Whisper |
+| `OPENAI_URL` | OpenAI API base URL (default `https://api.openai.com/v1`) |
+| `LOCAL_WHISPER_URL` | Local faster-whisper base URL (default `http://localhost:8000/v1`) |
+| `LOCAL_WHISPER_API_KEY` | API key for local server (often unused) |
+| `LOCAL_WHISPER_MODEL` | Model name for local transcription |
+| `REMOTE_WHISPER_MODEL` | Model name for Ollama-host transcription |
+| `TRANSCRIPTION_TIMEOUT` | Job/HTTP timeout in seconds (default `600`) |
+| `QUEUE_CONNECTION` | Use `database` (default) so transcription runs in the background |
+
+Ensure `APP_URL` matches how you access the app (default `http://localhost:8000`).
+
+## Running locally
+
+Start the app, queue worker, and Vite together:
+
+```bash
+composer run dev
+```
+
+Or separately:
+
+```bash
+php artisan serve
+php artisan queue:work
+npm run dev
+```
+
+Open [http://localhost:8000/recordings](http://localhost:8000/recordings).
+
+Transcription jobs are queued — keep a queue worker running or jobs will stay pending.
+
+## Usage
+
+1. **Upload** an MP3 from Recordings → Upload (optional title override).
+2. Open the recording and choose a transcription engine.
+3. Wait for the queue job to finish, then refresh to view or copy the transcript.
+4. Search the list by title, artist, or transcript text.
+
+## Transcription engines
+
+| Driver | When to use | Needs |
+| --- | --- | --- |
+| `cloud` | Fastest path; audio leaves your machine | `OPENAI_API_KEY` |
+| `local` | Confidential; audio stays on this machine | faster-whisper-server at `LOCAL_WHISPER_URL` |
+| `ollama` | Another machine on your network | Host URL + OpenAI-compatible `/v1/audio/transcriptions` |
+
+## Tests
+
+```bash
+composer test
+# or
+php artisan test
+```
+
+## License
+
+MIT