spoiler-remover

Scrub spoilers from your sports match recordings. Uses AssemblyAI to transcribe the audio and an OpenAI-compatible LLM to identify commentary about other matches, then mutes those segments with ffmpeg.

Requirements

• Python 3.12+
• ffmpeg
• AssemblyAI API key (ASSEMBLYAI_API_KEY)
• OpenAI-compatible API key (OPENAI_API_KEY) and model (OPENAI_MODEL)

Usage

python main.py <video_file> <team1> <team2> [other_team1] [other_team2] [third_team1] [third_team2]

Arguments:

Argument	Description
video_file	Path to the video file to process
team1	Name of the first team in the match you are watching
team2	Name of the second team in the match you are watching
other_team1 / other_team2	(Optional) Teams in a concurrent match whose score you want to mute
third_team1 / third_team2	(Optional) Teams in a third concurrent match whose score you want to mute

The script outputs <video_file>.unspoiled.<ext> with the spoiler segments muted.

How it works

1. Converts the video to WAV with ffmpeg
2. Transcribes the audio using AssemblyAI, producing an SRT
3. Sends the transcript to the LLM, which returns the IDs of spoiler sentences
4. Mutes the identified segments in the original video using ffmpeg's volume filter

Running with uv

The script uses inline script metadata and can be run directly with uv:

uv run main.py <video_file> <team1> <team2>