FreeEd4Med Media SuperTool v10.19 — Complete User Manual

1. Introduction & Overview

The FreeEd4Med Media SuperTool is a comprehensive bash-based media production toolkit designed specifically for creating therapeutic music content, lyric videos, audio visualizations, and properly formatted media for streaming platforms.

📸 Screenshot: Main Menu Overview

main_menu.png

Key Features

AI-Powered Transcription: Generate synchronized lyrics using OpenAI Whisper
Professional Typography: Full control over fonts, colors, positioning, and alignment
Audio Visualizers: Create stunning circular waveforms, spectrum analyzers, and fractal backgrounds
Metadata Management: Format-aware tagging for MP3, FLAC, WAV files
Social Media Export: One-click batch generation for TikTok, YouTube, and X (Twitter)
Notation Studio: AI-powered audio-to-MIDI-to-sheet-music workflow
DistroKid Validation: Check files meet streaming platform requirements

System Requirements

Component	Requirement
Operating System	Linux (Ubuntu 20.04+ recommended)
Shell	Bash 4.0+
FFmpeg	4.0+ with libx264, aac codecs
Python	3.8+ (for Whisper, Demucs, Basic-Pitch)
RAM	8GB minimum (16GB for AI features)
GPU	CUDA-compatible (optional, speeds up AI)

2. Installation & Dependencies

2.1 Core Dependencies

Install the essential tools first:

# Update package list and install core tools
sudo apt update
sudo apt install ffmpeg bc

# Verify installation
ffmpeg -version
ffprobe -version
bc --version

📸 Screenshot: Terminal showing successful ffmpeg installation

install_ffmpeg.png

2.2 Optional Dependencies

Aegisub (Subtitle Editor)

sudo apt install aegisub

OpenAI Whisper (AI Transcription)

# Create conda environment (recommended)
conda create -n audio_tools python=3.10
conda activate audio_tools

# Install Whisper
pip install openai-whisper

# For GPU acceleration (optional)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

BBC Audiowaveform (High-Quality Thumbnails)

sudo apt install audiowaveform

Notation Studio Dependencies

# Stem separation
pip install demucs

# Audio to MIDI
pip install basic-pitch

# PDF rendering
sudo apt install musescore3

# Guitar tabs
sudo apt install tuxguitar

The script automatically activates the audio_tools conda environment on startup. Make sure your environment is named accordingly or modify line 21 of the script.

2.3 Making the Script Executable

# Navigate to the script location
cd /path/to/freeed_media_super_tool.sh

# Make executable
chmod +x freeed_media_super_tool.sh

# Run the script
./freeed_media_super_tool.sh

📸 Screenshot: Script launching with dependency check

script_launch.png

3. Getting Started

3.1 Launching the Tool

When you run the script, you'll see the main menu with 8 options:

=======================================
   FreeEd4Med Media SuperTool v10.19      
=======================================
1. Creation Module (Lyrics, AI Whisper, Loop)
2. Visualizer Lab (Color Picker, Circular, etc.)
3. Branding & Metadata (Smart Logo, Tags)
4. Audio Lab (Convert, Normalize)
5. Social Media Batch (TikTok + YT + X)
6. Diagnostics (DistroKid Check)
7. Notation Studio (AI Transcription)
8. Exit

Enter choice [1-8]:

3.2 File Input Methods

Throughout the tool, you'll be prompted to provide file paths. You can:

Drag and Drop: Simply drag a file from your file manager into the terminal
Type the Path: Enter the full path manually (e.g., /home/user/music/song.mp3)
Use Tab Completion: Start typing and press Tab to autocomplete

The script automatically strips quotes from drag-and-drop paths. Both single and double quotes are handled.

3.3 Understanding Output Locations

By default, output files are saved in the same directory as the input file. When prompted for an output filename, you can:

Enter just a filename: output.mp4 (saves next to input)
Enter a full path: /home/user/exports/output.mp4

📸 Screenshot: File input prompt with drag-and-drop example

file_input.png

4. Module 1: Creation & Lyric Videos

The Creation Module is your primary workspace for generating synchronized lyric videos from audio files.

📸 Screenshot: Creation Module submenu

creation_menu.png

4.1 AI Whisper Subtitle Generation

This feature uses OpenAI's Whisper model to automatically transcribe audio and generate synchronized .SRT subtitle files.

How It Works

Select option 1 from the Creation Module menu
Drag your audio file (vocals work best for lyrics)
Whisper analyzes the audio and generates timestamps
An .SRT file is created in the same directory as your audio

# Behind the scenes, the script runs:
whisper "$input_file" --model small --output_format srt --output_dir "$output_dir"

📸 Screenshot: Whisper transcription in progress

whisper_progress.png

Model Options

Model	Speed	Accuracy	VRAM Required
tiny	Fastest	Basic	~1 GB
base	Fast	Good	~1 GB
small	Medium	Very Good	~2 GB
medium	Slow	Excellent	~5 GB
large	Slowest	Best	~10 GB

The script uses the "small" model by default for a good balance of speed and accuracy. For isolated vocal tracks, this typically achieves 95%+ accuracy.

4.2 Subtitle Editing with Aegisub

After generating subtitles, you'll often need to make corrections. Option 2 launches Aegisub for professional subtitle editing.

📸 Screenshot: Aegisub interface with subtitle timeline

aegisub_interface.png

Common Aegisub Tasks

Fix timing: Drag subtitle blocks on the timeline
Correct lyrics: Double-click to edit text
Merge lines: Select multiple and use Edit → Join Lines
Split lines: Position cursor and use Edit → Split Line

Save your Aegisub project as .ASS format for maximum styling control, or .SRT for universal compatibility.

4.3 Rendering Lyric Videos

Option 3 combines your background image, audio, and subtitle file into a finished lyric video.

Step-by-Step Workflow

Select a background image (1920x1080 recommended)
Select your audio file
Select your .SRT or .ASS subtitle file
Configure typography settings (see Section 10)
Enter output filename
Wait for rendering to complete

📸 Screenshot: Typography customization menu

typography_menu.png

Typography Options Available

Font Family: Arial, Times New Roman, Courier New, Comic Sans MS, Impact, or custom
Font Color: White, Yellow, Cyan, Purple, Black
Effects: Standard (outline + shadow), Clean, Hard Outline, Soft Shadow
Position: Bottom/Middle/Top vertical, Left/Center/Right horizontal
Justification: Left, Center, Right, or Justified text

📸 Screenshot: Final rendered lyric video frame

lyric_video_result.png

4.4 Static Image & Loop Videos

Static Image + Song (Option 4)

Creates a video from a single image that plays for the full duration of your audio:

ffmpeg -loop 1 -i "$image" -i "$audio" \
  -c:v libx264 -tune stillimage \
  -c:a aac -b:a 320k \
  -pix_fmt yuv420p -shortest "$output"

Loop Short Clip + Song (Option 5)

Takes a short video clip and loops it to match your audio duration:

# Calculate loop count
loop_count=$(echo "$audio_duration / $video_duration" | bc)

ffmpeg -stream_loop "$loop_count" -i "$video" -i "$audio" \
  -map 0:v -map 1:a \
  -c:v libx264 -shortest -pix_fmt yuv420p "$output"

For seamless loops, use video clips that are designed to loop (matching first/last frames) or use abstract/slowly moving content where cuts won't be noticeable.

5. Module 2: Visualizer Lab

The Visualizer Lab creates stunning audio-reactive videos using FFmpeg's powerful filter system.

📸 Screenshot: Visualizer Lab menu

visualizer_menu.png

5.1 The Portal (Circular Waveform)

Creates a mesmerizing circular waveform effect that radiates from the center of your background image.

📸 Screenshot: Portal visualizer output frame

portal_visualizer.png

Technical Details

This visualizer uses polar coordinate transformation to wrap a standard waveform into a circle:

[0:a]aformat=channel_layouts=mono,showwaves=s=1280x720:mode=cline:colors=${wave_color}:draw=full,
geq='p(mod(W/PI*(PI+atan2(H/2-Y,X-W/2)),W), H-2*hypot(H/2-Y,X-W/2))':
    a='alpha(mod(W/PI*(PI+atan2(H/2-Y,X-W/2)),W), H-2*hypot(H/2-Y,X-W/2))'[a]

Color Options

White (default)
Black
MadMooze Purple (violet)
Cyan
Custom (enter color name or hex code)

5.2 Symmetrical Waves (Cline Mode)

A horizontally-centered waveform overlay using FFmpeg's "cline" (center line) mode for symmetrical visualization.

📸 Screenshot: Symmetrical wave visualizer

symmetrical_waves.png

[0:a]aformat=channel_layouts=mono,
showwaves=s=1280x720:mode=cline:rate=30:colors=${wave_color}[waveform]

5.3 MadMooze Master Visualizer

A multi-panel professional visualizer combining vectorscope, spectrum analyzer, and waveform with artist/title overlay.

📸 Screenshot: MadMooze Master three-panel visualizer

madmooze_master.png

Panel Layout

Panel	Position	Size
Vectorscope	Top-Left	640x518
Spectrum	Top-Right	640x518
Waveform	Bottom	1280x202

[0:a]avectorscope=s=640x518,pad=1280:720[vs];
[0:a]showspectrum=mode=separate:color=magma:scale=cbrt:s=640x518[ss];
[0:a]showwaves=s=1280x202:mode=line:colors=violet[sw];
[vs][ss]overlay=w[bg];
[bg][sw]overlay=0:H-h,
drawtext=fontcolor=white:fontsize=24:x=20:y=20:text='${title} - ${artist}'[out]

5.4 Scrolling Spectrum (Heatmap)

A full-screen scrolling spectrogram using the "magma" color palette, ideal for detailed frequency analysis videos.

📸 Screenshot: Scrolling spectrum heatmap

spectrum_heatmap.png

[0:a]showspectrum=slide=scroll:mode=combined:color=magma:fscale=log:scale=sqrt:legend=1:s=1920x1080[v]

5.5 Mandelbrot Zoom (Fractal)

Combines a continuously zooming Mandelbrot fractal background with audio-reactive waveforms.

📸 Screenshot: Mandelbrot fractal with waveform overlay

mandelbrot_fractal.png

Fractal rendering is CPU-intensive. Expect longer render times compared to other visualizers.

5.6 Static Thumbnails (BBC & FFmpeg)

Generates high-quality static waveform images for use as album art, social media posts, or video thumbnails.

📸 Screenshot: Generated waveform thumbnail examples

waveform_thumbnails.png

Two Methods Available

BBC Audiowaveform: Higher quality, more options, saves as *_bbc_wave.png
FFmpeg showwavespic: Universal, transparent background, saves as *_transparent.png

# BBC Audiowaveform command
audiowaveform -i "$input" -o "${base}_bbc_wave.png" \
  -w 1280 -h 720 --no-axis-labels \
  --background-color 00000000 --waveform-color "$hex_color"

# FFmpeg showwavespic command
ffmpeg -i "$input" \
  -filter_complex "aformat=channel_layouts=mono,showwavespic=s=1280x720:colors=${wave_color}" \
  -frames:v 1 "${base}_transparent.png"

6. Module 3: Branding & Metadata

📸 Screenshot: Branding module menu

branding_menu.png

6.1 Video Stitching (Intro + Main + Outro)

Concatenates three video segments with automatic scaling and padding to ensure consistent 1920x1080 output.

Process

Select your INTRO video
Select your MAIN video
Select your OUTRO video
All videos are scaled, padded, and concatenated

[0:v]scale=1920:1080:force_original_aspect_ratio=decrease,
     pad=1920:1080:(ow-iw)/2:(oh-ih)/2,setsar=1[v0];
# Repeated for each input, then:
[v0][0:a][v1][1:a][v2][2:a]concat=n=3:v=1:a=1[v][a]

6.2 Pro Metadata Editor

A format-aware metadata editor that handles MP3, FLAC, WAV, and other formats with appropriate tag systems.

📸 Screenshot: Metadata editor prompts

metadata_editor.png

Supported Fields

Field	Description
Title	Track title
Artist	Performer name
Album	Album or release name
Year	Release year (stored as "date")
Composer	Producer/songwriter
Copyright	Rights holder information
Comment	Website, notes, or description

WAV files have limited metadata support. The tool will offer to convert to FLAC for better tagging capabilities.

6.3 Smart Logo/Watermark

Overlay a logo or watermark on your video with precise control over size, position, and opacity.

📸 Screenshot: Watermark position and size options

watermark_options.png

Size Options

Small (10% of video width)
Medium (20% - default)
Large (30%)
XL (40%)
Giant (50%)

Position Options

Bottom-Right (default)
Bottom-Left
Top-Right
Top-Left
Center

Style Options

Solid (100% visible)
Watermark (50% transparent)
Ghost (30% transparent)

[1:v][0:v]scale2ref=w=iw*${scale_factor}:h=-1[logo][main];
[logo]format=rgba,colorchannelmixer=aa=${opacity}[transp_logo];
[main][transp_logo]overlay=${position}

7. Module 5: Social Media Batch Generator

Automatically generates platform-optimized versions of your video for major social media platforms.

📸 Screenshot: Social media batch generation in progress

social_batch.png

Output Formats

Platform	Aspect Ratio	Video Codec	Audio
TikTok	9:16 (1080x1920)	H.264, blurred background fill	Copy
YouTube	Original	H.264 slow preset, CRF 18	AAC 320k
X (Twitter)	Original	H.264, 3500k bitrate	AAC 160k

TikTok Vertical Conversion

The TikTok version creates a 9:16 vertical video with your original content centered and a blurred version filling the background:

split[original][copy];
[copy]scale=-1:1920,boxblur=20:20[blurred];
[blurred]crop=1080:1920[bg];
[bg][original]overlay=(W-w)/2:(H-h)/2

📸 Screenshot: TikTok vertical format example

tiktok_format.png

8. Module 6: Diagnostics & Validation

📸 Screenshot: Diagnostics menu

diagnostics_menu.png

8.1 Stream Info (JSON)

Displays complete technical information about any media file in JSON format:

ffprobe -loglevel quiet -show_format -show_streams -i "$input" -print_format json

8.2 Silence/Black Frame Detection

Scans your file for silence longer than 2 seconds:

ffmpeg -i "$input" -af "silencedetect=noise=-50dB:d=2" -f null -

8.3 DistroKid/Streaming Validator

Checks if your WAV master meets streaming platform requirements:

📸 Screenshot: DistroKid validator output

distrokid_validator.png

Checks Performed

Sample Rate: Must be ≥44100 Hz
Bit Depth: 24-bit integer preferred (32-bit float triggers warning)

DistroKid and most distributors prefer 44.1kHz or 48kHz sample rates and 16-bit or 24-bit integer WAV files. 32-bit float files may be rejected or converted incorrectly.

9. Module 7: Notation Studio (AI)

The Notation Studio provides an AI-powered workflow for converting audio recordings into sheet music.

📸 Screenshot: Notation Studio menu

notation_menu.png

9.1 Full Workflow (Audio → Separate → MIDI → PDF)

Step 1: Stem Separation with Demucs

Demucs separates your audio into individual stems (vocals, drums, bass, other):

demucs -n htdemucs_ft "$input" -o "$project_dir"

📸 Screenshot: Demucs stem separation in progress

demucs_separation.png

Step 2: MIDI Transcription with Basic-Pitch

Basic-Pitch analyzes the selected stem and converts it to MIDI:

basic-pitch "$output_dir" "$stem_file"

Step 3: PDF Rendering with MuseScore

MuseScore converts the MIDI file to professional sheet music PDF:

musescore3 -o "${stem_base}.pdf" "$midi_file"

📸 Screenshot: Final sheet music PDF output

sheet_music_output.png

9.2 Quick Convert (MIDI → PDF)

If you already have a MIDI file, this option converts it directly to PDF sheet music.

9.3 Guitar Tabs Helper

Launches TuxGuitar for creating and editing guitar tablature.

10. Typography & Alignment Engine

The typography engine provides professional control over how lyrics and text appear in your videos.

📸 Screenshot: Full typography customization flow

typography_full.png

10.1 Font Selection

Option	Font Name	Style
1	Arial	Standard Sans-Serif
2	Times New Roman	Classic Serif
3	Courier New	Monospace/Typewriter
4	Comic Sans MS	Casual/Comic
5	Impact	Bold/Meme
6	Custom	Enter any installed font name

10.2 ASS Alignment Codes

The script uses ASS (Advanced SubStation Alpha) alignment codes based on a numpad layout:

┌─────────────────────────────┐
│  7 (Top-Left)    8 (Top)    9 (Top-Right)  │
│  4 (Mid-Left)    5 (Center) 6 (Mid-Right)  │
│  1 (Bot-Left)    2 (Bottom) 3 (Bot-Right)  │
└─────────────────────────────┘

10.3 Color Codes (ASS Format)

ASS uses &HBBGGRR format (blue-green-red, reversed from RGB):

Color	ASS Code
White	&H00FFFFFF
Yellow	&H0000FFFF
Cyan	&H00FFFF00
Purple	&H00800080
Black	&H00000000

10.4 Wrap Styles

Value	Behavior
0	Smart wrapping, top line wider
1	End-of-line word wrapping (default)
2	No word wrapping
3	Smart wrapping, bottom line wider

📸 Screenshot: Different typography style examples

typography_examples.png

11. Troubleshooting

Common Issues

"ffmpeg is not installed"

sudo apt update && sudo apt install ffmpeg

"whisper: command not found"

# Make sure conda environment is activated
conda activate audio_tools

# Reinstall whisper
pip install --upgrade openai-whisper

Aegisub Won't Launch

# Set environment variable to suppress warnings
export WXSUPPRESS_SIZER_FLAGS_CHECK=1

# Try reinstalling
sudo apt install --reinstall aegisub

Subtitle Rendering Shows Wrong Font

Make sure the font is installed system-wide:

# List available fonts
fc-list | grep -i "FontName"

# Refresh font cache
fc-cache -fv

Video Has No Audio

Check that your audio file is valid:

ffprobe -i your_audio.mp3

DistroKid Validator Shows 32-bit Float Warning

Convert to 24-bit integer:

ffmpeg -i input.wav -acodec pcm_s24le -ar 44100 output_24bit.wav

📸 Screenshot: Common error messages and solutions

troubleshooting_errors.png

Appendix A: FFmpeg Cheat Sheet

For the comprehensive FFmpeg cheat sheet, see: FFmpeg Cheat Sheet (Full Document)

Quick Reference

Basic Conversion

# Convert MP3 to WAV
ffmpeg -i input.mp3 output.wav

# Convert WAV to FLAC
ffmpeg -i input.wav -compression_level 5 output.flac

# Convert video to MP4 (H.264 + AAC)
ffmpeg -i input.avi -c:v libx264 -c:a aac output.mp4

Audio Normalization

# Normalize to -14 LUFS (streaming target)
ffmpeg -i input.wav -af loudnorm=I=-14:TP=-1:LRA=11 output.wav

Extract Audio from Video

ffmpeg -i video.mp4 -vn -acodec copy audio.aac
ffmpeg -i video.mp4 -vn -acodec pcm_s16le audio.wav

Appendix B: Color Codes Reference

Terminal Colors (ANSI Codes)

Color	Code	Variable
Purple	\033[1;35m	$PURPLE
Cyan	\033[0;36m	$CYAN
Green	\033[0;32m	$GREEN
Red	\033[0;31m	$RED
Yellow	\033[1;33m	$YELLOW
No Color (Reset)	\033[0m	$NC

FFmpeg Named Colors

Common colors accepted by FFmpeg filters:

white, black, red, green, blue, yellow, cyan, magenta
violet, orange, pink, purple, brown, gray, navy, teal
gold, silver, lime, aqua, fuchsia, maroon, olive

Hex Color Format

# For audiowaveform (RGB hex without #)
ffffff  # white
8A2BE2  # violet/purple
00FFFF  # cyan

# For FFmpeg (0x prefix or named)
0xFFFFFF or white
0x8A2BE2 or violet