Maj Scripts, vibe version

LLMs have changed the way the programming world works. Welcome to the machine-made code era! 🤖

Overview

maj-scripts-vibe is a home for utility scripts, all vibe-coded. 😎

If you're just here to use a script, start here. This README is the friendly map:

• Each script section tells you what the script does, what it needs, and the safest first commands to try.
• Use Your Local Setup when Python, Git, ffmpeg, or package managers need a little help.
• Use Friendly Launchers if you prefer double-clicks, drag-and-drop, file pickers, or right-click actions.

Table of Contents

• Overview
• Scripts
  • wh
  • whisper
• Your Local Setup
  • Friendly Launchers
  • Python
  • Git
  • Package Managers
• Contributing Docs

Scripts

wh

wh is a convenience wrapper for magic-wormhole.

What It Does

• wraps the wormhole CLI
• auto-adds --code-length=4 for code-generating flows
• passes all other commands through normally
• can help install wormhole when it is missing

Supported Platforms

• macOS
• Linux
• Windows

Dependencies

Shared prerequisites:

• Python
• shared setup from macOS, Linux, or Windows

Primary external tool:

• wormhole

Install / First Run Summary

Basic first run:

wh send file.zip

If wormhole is missing, wh can suggest a likely install route and offer to run it for you.

Common Usage Examples

Send a file with a shorter generated code:

wh send file.zip

Receive using the normal prompt flow:

wh receive

Receive while allocating the code on this side:

wh receive --allocate

Pass through other wormhole commands:

wh help

Important Behavior / Defaults

• wh injects --code-length=4 for send and tx.
• wh also injects --code-length=4 for receive --allocate and receive aliases such as rx, recv, and recieve.
• wh does not inject another code-length flag if you already passed --code-length.
• wh leaves ordinary receive unchanged because the sender normally generates the code.
• Missing-wormhole install prompts use Y/n, where Enter means yes.

Notes / Caveats

• Package-manager support varies by system, so wh suggests the best install route it can find.

↑ TOC

whisper

whisper is a self-bootstrapping subtitle and transcription CLI.

What It Does

• accepts a media file or folder
• discovers supported audio/video files
• builds and manages its own Python runtime
• selects a backend based on the host, including MLX on Apple Silicon
• normalizes common Bible-reference formatting mistakes by default, such as Psalm 83 18 to Psalm 83:18
• writes subtitles by default, can also write plain-text transcripts, and can mux soft subtitle tracks into video containers

Supported Platforms

• macOS
• Linux
• Windows

MLX support is for Apple Silicon on macOS. Other environments use faster-whisper.

Dependencies

Shared prerequisites:

• Python
• shared setup from macOS, Linux, or Windows

Useful system dependency:

• ffmpeg for media workflows, especially default speech-onset subtitle trimming, subtitle burn-in, and subtitle-track embedding

Script-specific note:

• On Apple Silicon, MLX runtimes can auto-select a more stable managed-runtime Python.

Install / First Run Summary

Basic first run:

whisper /path/to/file.mp4

Useful inspection/setup commands:

whisper --doctor
whisper --doctor --json
whisper --doctor --deep
whisper --setup-only

On first run, whisper will:

• inspect the host
• choose a managed runtime
• install required Python packages into that runtime
• prompt before downloading packages unless -y / --yes is used

Common Usage Examples

Transcribe one file:

whisper /path/to/file.mp4

Transcribe multiple explicit files from shell expansion:

whisper *.mkv
whisper *.mp3 *.mp4

Opt in to spoken Bible-reference parsing:

whisper /path/to/file.mp4 --bible-reference-phrases

Use a stricter subtitle readability profile:

whisper /path/to/file.mp4 --subtitle-style=strict

Layer in a custom glossary and review what postprocessing still looks suspicious:

whisper /path/to/file.mp4 --glossary=/path/to/whisper-glossary.txt --review-postprocessing

Suppress a known intro or outro from a shared phrase list:

whisper /path/to/file.mp4 --suppress-phrases=/path/to/whisper-suppress.txt

Write a plain-text transcript next to the normal subtitle output:

whisper /path/to/file.mp4 -t
whisper /path/to/file.mp4 --transcript
whisper /path/to/file.mp4 -t --paragraphs

Write only the transcript:

whisper /path/to/file.mp4 -T
whisper /path/to/file.mp4 --transcript-only

Write a speaker-labeled transcript:

whisper /path/to/file.mp4 -T --speaker-labels --paragraphs
whisper /path/to/file.mp4 -T --diarize

Preview the work plan without setup, installs, or transcription:

whisper /path/to/file.mp4 --plan
whisper /path/to/folder --recursive --plan --json

Create a tiny video plus matching subtitle sidecar for manual embed checks:

whisper --make-sample-media=/tmp/whisper-sample.mp4
whisper /tmp/whisper-sample.mp4 --embed-file

Retranscribe even when the expected subtitle or video output already exists:

whisper /path/to/file.mp4 --force

Keep repeated defaults in a project-local TOML config:

# .maj-scripts-whisper.toml
lang = "en"
subtitle_style = "strict"
speaker_labels = false
glossary = ["./whisper-glossary.txt"]
suppress_phrases = ["./whisper-suppress.txt"]

Transcribe recursive matches in batches instead of starting one whisper process per file:

find . -type f -name '*.mp4' -exec whisper '{}' +
find . -type f -name '*.mp4' -print0 | xargs -0 whisper

Choose a model explicitly:

whisper /path/to/file.mp4 --model=medium

Choose a language explicitly:

whisper /path/to/file.mp4 -l en

Write output to a chosen folder:

whisper /path/to/file.mp4 --outdir=/path/to/output

Embed a soft subtitle track into the output video:

whisper /path/to/file.mp4 --embed

Embed a soft subtitle track and replace the source video after muxing succeeds:

whisper /path/to/file.mp4 -e -i

Embed an edited matching sidecar subtitle file without retranscribing:

whisper /path/to/file.mp4 -f
whisper /path/to/file.mp4 -f /path/to/file.srt -i

Burn subtitles into a new video with an explicit AV1 encoder:

whisper /path/to/file.mp4 --burn --burn-vcodec=libsvtav1

Run MLX comparison diagnostics:

whisper /path/to/file.mp4 --mlx-word-timestamps=off
whisper /path/to/file.mp4 --mlx-output-format=text
whisper /path/to/file.mp4 --model=tiny --mlx-word-timestamps=off --mlx-output-format=text

Important Behavior / Defaults

• The script self-manages its runtime instead of requiring a manually prepared virtualenv.
• On Apple Silicon, MLX runtimes can auto-select a more stable managed-runtime Python.
• Default model selection is hardware-aware.
• --plan / --dry-run shows discovered files, selected backend/model, output paths, configured glossary and suppression files, speaker-label status, embed/burn actions, and whether ffmpeg is required without installing packages or transcribing.
• Normal --doctor checks installed runtime modules without importing native backends, which keeps routine diagnostics calmer around MLX/Metal crashes.
• --doctor --json prints machine-readable diagnostics for scripts, CI, and support notes.
• --doctor --deep explicitly imports installed runtime backends for deeper diagnostics. Use it when you want to isolate backend import failures and are comfortable with native packages being loaded.
• --make-sample-media=PATH creates a tiny video and matching .srt sidecar so you can test --embed-file without hunting for a media fixture.
• Existing expected outputs are skipped by default, so reruns resume safely instead of retranscribing finished files. Use --force to overwrite that skip behavior.
• -t / --transcript writes a .txt transcript alongside normal .srt/.ass output. If the expected sidecar subtitle already exists, it builds the transcript from that file instead of retranscribing unless --force is set.
• -T / --transcript-only writes only the .txt file and skips subtitle/video outputs.
• --paragraphs formats transcript text with blank lines between likely paragraphs, based on timing gaps and sentence boundaries. It does not affect subtitle output.
• --speaker-labels adds anonymous Speaker 1, Speaker 2, and similar labels to transcript output. It implies transcript output, leaves subtitles unlabeled, and has --diarize as a technical alias.
• Speaker labels are fully optional. They install larger ML packages only when requested, show a size warning first, reuse an existing global Hugging Face speaker model cache when one is already present, and otherwise keep speaker model files in the managed runtime area.
• --clean-speaker-labels removes optional speaker-label packages and the app-owned speaker-label model cache. It does not touch global Hugging Face caches.
• You can pass multiple explicit files and folders in one command, and duplicate matches are skipped after the first one.
• If you're using find, prefer batched forms such as -exec whisper '{}' + or xargs -0 whisper; plain -exec whisper '{}' \; launches a fresh whisper process for every file.
• Reusable CLI defaults can live in ~/.config/maj-scripts/whisper/config.toml globally or .maj-scripts-whisper.toml in a project. Precedence is built-in defaults, global config, nearest project config, then CLI flags.
• Config files use TOML. Use glossary = [...] or suppress_phrases = [...] to replace earlier config-layer lists, and extra_glossary = [...] or extra_suppress_phrases = [...] to append to them.
• Common JW/Bible and general capitalization such as Jehovah, Governing Body, Kingdom Hall, Bible, jw.org, OpenAI, ChatGPT, YouTube, and Wi-Fi is normalized by default.
• Project glossary files named .whisper-glossary.json, .whisper-glossary.txt, whisper-glossary.json, or whisper-glossary.txt are auto-loaded from parent folders when present. You can stack extra glossary files explicitly with repeated --glossary=PATH.
• Text glossary files use source => Replacement lines, while JSON glossary files can be a plain object of string replacements. Suppression text files accept optional start:, end:, or any: prefixes per line, and JSON suppression files can use matching start, end, and any keys.
• Bible references such as Psalm 83 18, Psalm 83-18, Psalm 83.18, Psalm 8318, and range forms like Psalm 83 18 19 are normalized by default. Use --no-bible-reference-normalization to opt out.
• Spoken forms such as Psalm 83 verse 18, Psalm chapter 83 verse 18, and 1 John chapter 4 verse 8 are available as an opt-in with --bible-reference-phrases.
• Subtitle cue starts and ends are speech-trimmed by default to avoid long lead-ins and long tails over music or ambient audio. Timed-word edges that sit outside detected speech are also pruned conservatively, cue timing is smoothed for readability, and obvious repeated-word glitches are collapsed conservatively when timed words are available. Use --no-speech-trim to opt out of the speech-aware cleanup pass.
• --subtitle-style=balanced|strict lets you keep the current balanced defaults or switch to a stricter readability profile with tighter line width and lower chars-per-second targets.
• Known boilerplate intros and outros can be suppressed with --suppress-phrases=PATH, and project suppression files named .whisper-suppress.json, .whisper-suppress.txt, whisper-suppress.json, or whisper-suppress.txt are auto-loaded from parent folders when present.
• --review-postprocessing / --lint does not rewrite extra text on its own; it reports leftover spoken Bible-reference phrases, dense subtitle cues, and other postprocessing things you may want to inspect.
• --embed keeps the original media streams and adds a soft subtitle track when the container supports it directly.
• --embed-file uses an existing .srt or .ass instead of retranscribing, and bare -f / --embed-file looks for a matching subtitle file next to the video. It runs directly in the launcher Python, skips backend loading, and reuses source audio language metadata when available.
• --in-place first writes to a temporary file, then replaces the original video only after a successful mux. The short alias is -i.
• --font sets the font family used for ASS and karaoke subtitle output. The short alias is -F.
• MP4 and MOV use mov_text for embedded text subtitles; ASS subtitles fall back to MKV so styling survives.
• --burn always re-encodes video because subtitle burn-in uses an ffmpeg video filter.
• --burn-vcodec=auto lets ffmpeg choose the video encoder, or you can pass a codec such as libx264 or libsvtav1.
• MLX diagnostic flags are for comparison and investigation:
  • --mlx-word-timestamps=auto|on|off
  • --mlx-output-format=auto|subtitle|text
  • --mlx-model-default=wrapper|official
• The normal wrapper behavior stays subtitle-oriented unless you explicitly ask for a different comparison mode.

Notes / Caveats

• First-run setup can take longer because packages and models may need to be installed or downloaded.
• Speaker labels depend on pyannote and may require accepting model terms on Hugging Face plus setting HF_TOKEN or HUGGINGFACE_TOKEN.
• Soft subtitle embedding and burn-in both require ffmpeg, and the default speech-onset trim uses it when available.
• In-place embedding only works when the embedded output can stay in the same container; cases that need an MKV fallback still require plain --embed.
• MLX behavior can vary by machine, Python version, model choice, and the host Metal stack. If MLX fails or macOS reports that Python closed unexpectedly, try --backend=faster-whisper and use --doctor --deep only when you want an explicit native import check.

↑ TOC

Your Local Setup

Use this section for shared prerequisites and friendlier ways to run scripts without living in a terminal. Script-specific notes can link back here instead of repeating the same setup steps everywhere.

Friendly Launchers

These scripts stay command-line-first because that keeps them portable, scriptable, and easy to debug. Friendly launchers are thin wrappers around the same commands for people who prefer double-clicking, drag-and-drop, file pickers, or context menus.

Good launchers should:

• show command output or keep a log file so errors are not hidden
• pass selected files and folders through to the script without changing them
• keep the underlying command easy to inspect and edit
• rely on the shared Python, Git, and tool setup below

macOS Launchers

For a simple double-click launcher, create a .command file that runs a script from this repo. For drag-and-drop, create an Automator Application or Shortcuts workflow that accepts files or folders from Finder and passes them to the script.

Helpful macOS patterns:

• Finder Quick Actions work well for right-click workflows.
• Automator Applications work well for drag-and-drop workflows.
• A .command file should be executable with chmod +x.
• Keep Terminal visible while testing so setup prompts and errors are easy to see.

Example wrapper shape:

#!/bin/zsh
cd /path/to/maj-scripts-vibe || exit 1
./script-name "$@"

Windows Launchers

For Windows, use a PowerShell script, a .cmd file, or a shortcut in the Send to folder. The py launcher is the safest default because it forwards arguments to Python scripts predictably.

Helpful Windows patterns:

• A Send to shortcut works well for right-click file workflows.
• A PowerShell wrapper can keep the window open after errors.
• Start with one selected file while testing, then try multiple files.
• If Windows blocks a downloaded script, unblock it from file Properties or use a local wrapper you created yourself.

Example wrapper shape:

py C:\path\to\maj-scripts-vibe\script-name @args

Linux Launchers

For Linux desktops, use a .desktop launcher, a file-manager custom action, or a small shell wrapper. Nautilus, Nemo, Dolphin, and Thunar each expose custom actions a little differently, but the core idea is the same: pass selected files to the script and keep output visible.

Helpful Linux patterns:

• Use Terminal=true in .desktop launchers while testing.
• File-manager custom actions are often the best right-click workflow.
• A shell wrapper can normalize paths and write logs before calling the repo script.
• Desktop environments differ, so keep launcher docs practical rather than tied to one file manager.

Example .desktop command shape:

Exec=/path/to/maj-scripts-vibe/script-name %F
Terminal=true

Launcher Safety Notes

Treat launchers as convenience wrappers, not separate apps with different behavior. When a launcher is new, test it with a tiny throwaway file or a harmless preview command first. If a script offers a dry-run, doctor, or sample-file command, use that before handing it important files.

↑ TOC

Python

Most scripts in this repo are expected to use Python 3.

Check whether Python 3 is already available:

python3 --version

If that command works, you're probably already most of the way there. If not, the platform guidance below will help you get set up.

For this repo, a modern Python 3 release is the safe default.

Python setup by platform:

• macOS
• Linux
• Windows

Python on macOS

Do not assume a usable python3 is already present. A quick check first can save time:

python3 --version

If python3 is missing:

1. Install Homebrew if needed.
2. Install Python with Homebrew.

For scripts that need compiled dependencies or multimedia tools, Xcode Command Line Tools may also be useful:

xcode-select --install

Python on Linux

Python 3 is often available already, but it is still worth checking first:

python3 --version

If it is missing, Debian/Ubuntu-style setup is a good baseline:

sudo apt-get update
sudo apt-get install -y python3 python3-venv ffmpeg

Other distros should use their normal package manager equivalents.

Python on Windows

On Windows, it is best to treat Python installation as an explicit setup step rather than assuming it is already present.

When running Python scripts from this repo on Windows, the safest default is:

py <scriptname> [args]

The py launcher passes arguments after the script name through to the script itself.

First check:

py --version
python --version

If Python is missing, install it using one of these routes:

• Official Python installer: https://www.python.org/downloads/windows/
• a package manager such as winget or Chocolatey

After installation, verify:

py --version
python --version

↑ TOC

Git

Git is optional if you only want to download a ZIP and try one script. It becomes handy when you want to keep your local copy of this repo up to date without re-downloading everything by hand.

Check whether Git is already available:

git --version

If you have Git, you can make a local copy with:

git clone https://github.com/majal/maj-scripts-vibe.git
cd maj-scripts-vibe

Later, update that copy from inside the repo folder:

git pull

If Git feels like too much, downloading a fresh ZIP from GitHub is still okay. Git just makes updates tidier. If you prefer a visual app, GitHub Desktop can clone the repo and update it with Fetch/Pull buttons.

↑ TOC

Package Managers

Package managers help you install and update command-line tools without chasing individual downloads by hand.

Package manager setup by platform:

• Homebrew (macOS)
• winget and Chocolatey (Windows)

Homebrew (macOS)

Install Homebrew by following the official instructions:

• https://brew.sh/

Verify Homebrew:

brew --version

Common examples:

brew install python
brew install ffmpeg
brew install git

You can use the same pattern for other command-line tools as new scripts are added to this repo.

Verify installed tools as needed:

python3 --version
ffmpeg -version
git --version

winget and Chocolatey (Windows)

For most Windows users, winget is the simpler default choice because it is built into modern Windows versions. Chocolatey is also a solid option if you already use it.

Verify winget if available:

winget --version

Common examples with winget:

winget install Python.Python.3
winget install Gyan.FFmpeg
winget install Git.Git

Equivalent examples with Chocolatey:

choco install python
choco install ffmpeg
choco install git

You can use the same pattern for other command-line tools as new scripts are added to this repo.

Verify installed tools as needed:

py --version
ffmpeg -version
git --version
python --version

↑ TOC

Contributing Docs

When future scripts are added, keep this README as the main navigation page and update it alongside the script so new tools stay easy to discover.

Keep Your Local Setup generic and reusable. Script-specific requirements, caveats, and quality-of-life notes should live in the relevant script section instead.

For quick repo checks, run the lightweight test harness before or after changes:

python3 -m tests

On Windows, use:

py -m tests

The harness covers smoke checks for the top-level CLIs, README consistency checks, and focused behavior tests for wh and core whisper logic.

Detailed contributor and AI-agent rules live in AGENTS.md.

↑ TOC