Foxtitles

A designer-friendly GUI for transcribing audio/video and a companion After Effects panel.

What you get

• Foxtitles macOS app for transcription (no CLI needed).
• Foxtitles panel for After Effects.

System requirements

• Apple Silicon (M1/M2/M3/M4): Intel Macs are not supported by the current MLX-based transcription engine.
• macOS 14.0+ recommended.

User documentation

For an end-to-end walkthrough (every button/option in the GUI + After Effects panel), see docs/USER_GUIDE.md.

Technical notes & credits

For architecture details, model stack, build/packaging notes, and credits, see docs/TECHNICAL.md.

Sharing with non-technical friends

• The file to share is dist/Foxtitles-Release.zip. It’s large on purpose (it includes the app + Python runtime + dependencies + ffmpeg).
• The small Foxtitles-Source-*.zip is for building only; it will not run by itself.

Build the shareable zip (easiest)

1. Unzip the source zip.
2. Double-click MAKE_RELEASE.command.
3. When it finishes, share dist/Foxtitles-Release.zip.

If it stops with:

• “Python not found”: install Python 3.11+ from python.org, then run MAKE_RELEASE.command again.
• “FFmpeg not found”: install Homebrew (brew.sh), then run brew install ffmpeg, then run MAKE_RELEASE.command again.

TODO

Planned improvements are tracked in TODO.md.

Quick start for friends (no Terminal)

1. Unzip the release.
2. Double-click INSTALL.command (recommended).
   • Installs Foxtitles.app to ~/Applications
   • Installs Foxtitles.jsx into your user After Effects scripts folder
3. Restart After Effects and open:
   • Window -> Foxtitles
4. Select your video/audio layer + a style Text Layer, then click Process.

Notes:

• This build targets Apple Silicon (M‑series Macs).

Developer install (Terminal)

1. Open Terminal and go to the repo folder.

2. Run:

python3 -m venv .venv
. .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

Optional (enables drag-and-drop in the GUI):

pip install tkinterdnd2

Launch the GUI

./scripts/run_gui.sh

Or create a simple macOS app wrapper:

./scripts/create_launcher_app.sh

This creates dist/Foxtitles.app. Place the .app next to the repo folder so it can find scripts/run_gui.sh.

Build a bundled app (Apple Silicon)

This produces a self-contained .app with ffmpeg included.

./scripts/build_macos_app.sh
./scripts/package_release.sh

The release zip is dist/Foxtitles-Release.zip.

Package the source zip

./scripts/package_source_zip.sh

This creates dist/Foxtitles-Source.zip.

Using the GUI (quick guide)

1. Add files: click Add Files or Add Folder (drag-and-drop works if installed).
2. Choose output format (SRT is common).
3. Click Start Transcription.
4. When finished, you can open the output folder.
5. Select any file in the list to preview its transcription inside the app.

Preview tip: select a file and click Preview to open the audio/video.

After Effects (Foxtitles panel)

1. Copy the panel file:

after-effects/Foxtitles/Foxtitles.jsx

2. Paste it into:

/Applications/Adobe After Effects <version>/Scripts/ScriptUI Panels/

3. Restart After Effects.

4. Open the panel:

Window -> Foxtitles

After Effects workflow (CapCut-like)

1. Select your comp and the video layer you want markers on.
2. Click Generate and choose an SRT file.
3. Click Edit to fix text if needed.
4. Click Build to create subtitle layers.
5. Pick a Style source layer and click Apply Style to rebuild with that look.

After Effects handoff (optional)

The Foxtitles app writes a handoff file after each successful run:

~/Documents/Foxtitles/last_output.json

In the Foxtitles panel:

1. Click Run Foxtitles to launch the GUI (first time, pick the launcher path).
2. Transcribe and make sure SRT is one of the outputs.
3. Click Import Latest to bring the most recent SRT into the current comp.

Troubleshooting

• If the GUI doesn't open, re-run ./scripts/run_gui.sh from Terminal so it can show errors.
• The app runs locally and uses your Mac to process audio/video.

macOS security prompts

• If macOS blocks the app because it is from an unidentified developer:
  • Run INSTALL.command (it clears the quarantine flag), or
  • System Settings -> Privacy & Security -> scroll down -> allow/open anyway.