Generate captioned audiogram videos from any audio file. Audiogrammer transcribes your audio with OpenAI Whisper, then renders an MP4 with animated word-by-word subtitle highlighting over your chosen background — with an optional reactive audio waveform overlay.

• Word-by-word subtitle highlighting — current word highlighted, past words dimmed
• Background support: static image, animated GIF, or video (loops to match audio length)
• Audio trimming — pick an in/out highlight window in a waveform scrubber; only that window is transcribed and rendered
• Audio waveform overlay — reactive spectrum or progress style, with bars / line / circular looks
• Aspect ratio presets: 16:9, 9:16 vertical, 1:1 square, or native source size
• Optional transcript review and edit before rendering
• Watermark: text and/or image overlay with configurable position and opacity
• Font selector pulling from system fonts, with a bundled fallback
• Settings auto-save on close and auto-load on startup, plus a one-click Restore Defaults
• Cancel mid-render with automatic partial-file cleanup
• Runs fully offline — no API keys required

• Python 3.12+
• FFmpeg installed and available on your PATH
  • Linux: sudo apt install ffmpeg
  • macOS: brew install ffmpeg
  • Windows: download from ffmpeg.org
• tkinter (Linux only — usually needs a separate install)
  • sudo apt install python3-tk
• ~2 GB free disk space for Whisper model files (downloaded automatically on first use to ~/.cache/whisper/)

git clone https://github.com/gjjeffers/audiogrammer.git
cd audiogrammer
pip install -r requirements.txt

Using a virtual environment is recommended:

python -m venv .venv
# Windows:        .venv\Scripts\activate
# macOS / Linux:  source .venv/bin/activate
pip install -r requirements.txt

From the project root:

python main.py

On launch the app checks that the required packages (openai-whisper, moviepy, Pillow, numpy) are installed and prints an install hint if anything is missing. The desktop window then opens.

Basic workflow:

1. Input Files — browse for a background file (image, GIF, or video) and an audio file. Picking an audio file auto-suggests an output name next to it.
2. Settings — choose the Whisper model, resolution, quality, font, colors, font size, and FPS.
3. (Optional) Trim Audio… — open the dialog to select a highlight window in the audio; only that window is transcribed and rendered. Leave unset to process the entire file.
4. (Optional) Waveform Settings… — open the dialog to enable and configure the audio waveform overlay.
5. Output — confirm or change where the .mp4 is saved.
6. (Optional) Watermark — add text and/or an image overlay.
7. Click Generate Audiogram — the progress bar tracks transcription and then the render phase.
8. (Optional) Tick Review transcript before rendering to proofread and correct words before the render starts.

Your settings (including file paths and waveform options) are saved automatically when you close the window and restored the next time you open the app. Use Restore Defaults to reset everything.

Open the Trim Audio… dialog to select a highlight window instead of rendering the whole file. The status next to the button shows (full) or the chosen range.

Trimming happens before transcription, so picking a 60-second window means Whisper only processes those 60 seconds — dramatically faster than transcribing a full episode. The selection resets when you choose a different audio file.

Open via the Waveform Settings… button. The status next to the button shows (on) / (off). The overlay draws an audio-driven visualization on top of the background.

Models are downloaded automatically on first use.

Speed factor is relative to large (1×).

Settings are stored as JSON at ~/.audiogrammer/settings.json. They are written automatically when you close the window and loaded on startup. Delete that file (or click Restore Defaults) to start fresh.

• Social media verticals: use the Vertical 1080×1920 (9:16) preset for Reels, Shorts, and TikTok
• Podcasts: Square 1080×1080 (1:1) works well across most platforms
• Use High quality for final exports and Fast for quick previews
• For a punchy reactive waveform, pair Reactive mode with Rounded Bars, a higher Sensitivity, and some Smoothing to keep motion clean
• Cancelling during transcription takes effect after the Whisper pass completes — it cannot interrupt the model mid-run

This project is licensed under the MIT License - see the LICENSE file for details.