submit  ─►  ┌──────────────┐   one worker, one GPU   ┌───────────────┐
            │  job queue   │ ──────────────────────► │ WhisperEngine │
poll    ◄─  └──────────────┘   processed serially     └───────────────┘

pip install -e .        # or: uv sync

# MCP transport (streamable-http on :8000)
python server.py
python server.py --port 9000
python server.py --transport stdio        # for stdio MCP clients

# Flask transport (HTTP/JSON on :8001)
python flask_server.py
python flask_server.py --port 9001
python flask_server.py --debug            # Flask dev server with auto-reload

curl localhost:8001/ping

# submit
curl -X POST localhost:8001/transcriptions \
  -H 'Content-Type: application/json' \
  -d '{"audio_path":"/abs/path/audio.mp3","args":"--format text"}'
# → {"job_id":"j_ab12cd34","position":1, ...}

# poll until "status":"done"
curl localhost:8001/transcriptions/j_ab12cd34

# inspect the queue / cancel
curl localhost:8001/queue
curl -X POST localhost:8001/transcriptions/j_ab12cd34/cancel

python test_ping.py                       # ping the server
python test_live.py --audio /path/audio.mp3   # full submit → poll → print transcript

app/
  queue_manager.py   queue, worker, engine lifecycle, CLI-arg → kwargs bridge
  whisper/engine.py  faster-whisper wrapper (model stays loaded between jobs)
  models.py          JobRecord dataclass
  service.py         payload-shaping shared by both transports
  main.py / tools.py MCP transport (create_mcp_app + tool definitions)
  flask_app.py       Flask transport (create_flask_app + routes)
server.py            run the MCP server      (:8000)
flask_server.py      run the Flask server    (:8001)

command: python flask_server.py --port 8000

pytest -m "not integration"   # unit tests (engine mocked) — covers core, MCP, and Flask
pytest -m integration         # requires faster-whisper + a real model/audio file