media-utils

Media Utilities

Internal utilities for media assembly. Used by producer skills.

These scripts wrap FFmpeg to provide reliable media operations.

Prerequisites

• FFmpeg must be installed: brew install ffmpeg (macOS) or apt install ffmpeg (Linux)
• Check with: python3 check_ffmpeg.py

Available Utilities

audio_concat.py

Concatenate multiple audio files into one.

# Simple concatenation
python3 audio_concat.py -i intro.wav segment1.wav outro.wav -o podcast.mp3

# With crossfade between clips
python3 audio_concat.py -i track1.wav track2.wav --crossfade 2.0

# With normalization
python3 audio_concat.py -i *.wav -o mixed.mp3 --normalize

audio_mix.py

Mix voice/narration with background music (with optional ducking).

# Voice + music with ducking (music lowers when voice plays)
python3 audio_mix.py --voice narration.wav --music background.mp3 -o final.mp3

# Adjust music volume (default: 0.3)
python3 audio_mix.py --voice voice.wav --music music.mp3 --music-volume 0.2

# No ducking
python3 audio_mix.py --voice voice.wav --music music.mp3 --no-duck

# With fade in/out on music
python3 audio_mix.py --voice voice.wav --music music.mp3 --fade-in 2 --fade-out 3

video_concat.py

Concatenate multiple video clips.

# Simple concatenation
python3 video_concat.py -i clip1.mp4 clip2.mp4 clip3.mp4 -o final.mp4

# With fade transition
python3 video_concat.py -i *.mp4 -o final.mp4 --transition fade --duration 1.0

# Normalize to 1080p
python3 video_concat.py -i *.mp4 -o final.mp4 --resolution 1080p

# Available transitions: fade, dissolve, wipeleft, wiperight, slideup, slidedown

video_audio_merge.py

Add audio track(s) to video.

# Replace video audio
python3 video_audio_merge.py --video clip.mp4 --audio voiceover.mp3 -o final.mp4

# Add voice + music with ducking
python3 video_audio_merge.py --video clip.mp4 --voice narration.wav --music bg.mp3

# Mix with existing video audio
python3 video_audio_merge.py --video clip.mp4 --audio music.mp3 --mix

# Audio sync offset
python3 video_audio_merge.py --video clip.mp4 --audio audio.mp3 --offset 0.5

video_strip_audio.py

Remove audio from video files (for replacing with custom audio).

# Strip audio from single file
python3 video_strip_audio.py -i video.mp4 -o silent_video.mp4

# Strip audio from multiple files (batch mode)
python3 video_strip_audio.py -i clip1.mp4 clip2.mp4 clip3.mp4

# Strip with custom output directory
python3 video_strip_audio.py -i *.mp4 --output-dir ./silent/

# Re-encode video instead of copying
python3 video_strip_audio.py -i video.mp4 --reencode

check_ffmpeg.py

Verify FFmpeg installation.

python3 check_ffmpeg.py
# ✅ FFmpeg is available!
#    ffmpeg version 6.0 ...

report_to_pdf.py

Convert Markdown reports to professional PDF documents.

# Basic conversion
python3 report_to_pdf.py -i analysis.md -o analysis.pdf

# With custom title and executive style
python3 report_to_pdf.py -i report.md -o report.pdf --title "Q4 Market Analysis" --style executive

# Technical documentation with table of contents
python3 report_to_pdf.py -i docs.md -o docs.pdf --style technical --toc

Available styles:

Style	Description
business	Clean, professional (default)
executive	Executive summary with larger fonts
technical	Technical documentation
minimal	Minimal styling, maximum content

Requires: pip install markdown weasyprint

Usage by Producer Skills

These utilities are called by the producer skills to assemble final outputs:

from pathlib import Path
import subprocess
import sys

# Get path to media-utils
UTILS_PATH = Path(__file__).parent.parent.parent / "media-utils" / "scripts"

def concat_audio(files: list, output: str):
    cmd = [
        sys.executable,
        str(UTILS_PATH / "audio_concat.py"),
        "-i", *files,
        "-o", output
    ]
    subprocess.run(cmd, check=True)

Output Formats

Utility	Default Output	Options
audio_concat	MP3	Inherits from input
audio_mix	MP3	MP3
video_concat	MP4 (H.264)	MP4
video_audio_merge	MP4 (H.264)	MP4
video_strip_audio	MP4 (copy)	MP4