Bump Extractor

A GUI tool for manually extracting bumps (short video segments) from video files with intelligent naming assistance based on standardized naming conventions.

Features

• Video Playback with Audio: Built-in video player with full audio support
• Playback Controls: Play/pause button, skip forward/backward (±1s, ±5s, ±10s), and variable speed (0.25x - 2.0x)
• Timeline Scrubbing: Drag timeline to jump to any point in the video
• Mark Start/End Points: Click to mark the beginning and end of bump segments
• Smart Naming Form: Dynamic form that changes based on bump type selection
  • Generic bumps (no shows)
  • Single show bumps
  • Two-show transitional bumps
  • Three-show lineup bumps
• Real-time Filename Validation: See the generated filename update as you type
• FFmpeg Integration: Fast extraction using codec copy (no re-encoding)
• Session Tracking: Keeps history of all extracted bumps in SQLite database
• Extraction List: View all bumps extracted from current video
• Export Sessions: Save extraction history to CSV

Requirements

• Python 3.8 or higher
• FFmpeg installed and available in system PATH
• VLC media player installed (for video playback with audio)

Installation

1. Clone or download this repository

2. Install Python dependencies:

pip install -r requirements.txt

3. Install FFmpeg:

   macOS (using Homebrew):

   brew install ffmpeg

   Linux (Ubuntu/Debian):

   sudo apt-get install ffmpeg

   Windows:

   • Download from https://ffmpeg.org/download.html
   • Extract and add to system PATH

4. Install VLC media player:

   macOS (using Homebrew):

   brew install --cask vlc

   Linux (Ubuntu/Debian):

   sudo apt-get install vlc

   Windows:

   • Download from https://www.videolan.org/vlc/
   • Run installer

5. Verify installations:

ffmpeg -version
vlc --version

Usage

Starting the Application

Run the main script:

python main.py

First-Time Setup

On first launch, you'll see a setup dialog:

1. Channel Name: Enter the network/channel you're extracting for (e.g., "Toonami", "Cartoon Network", "Adult Swim")

   • This will be used as the network prefix in all bump filenames
   • A subfolder with this name will be created in your output folder

2. Output Folder: Select where extracted bumps should be saved

   • Browse to choose a folder
   • Make sure you have write permissions

Click OK to save configuration.

Extracting Bumps

1. Open a Video File

   • File → Open Video (or Ctrl+O)
   • Select the video file containing bumps
   • First frame will display

2. Navigate the Video

   • Play/Pause: Click the "▶ Play" button or press Spacebar
   • Skip Forward/Back: Use +1s, +5s, +10s, -1s, -5s buttons
   • Playback Speed: Use the Speed dropdown to adjust playback rate (0.25x to 2.0x)
   • Timeline Scrubbing: Drag the timeline slider to jump to any position
   • Audio plays during playback
   • Current time displays automatically

3. Mark Bump Segment

   • Scrub to the start of a bump
   • Click Mark Start button
   • Scrub to the end of the bump
   • Click Mark End button
   • Start/End times display in green/red

4. Extract the Bump

   • Click Extract Bump button
   • Naming form dialog appears

5. Fill Out Naming Form

   Select Bump Type:

   • Generic: For bumps without specific shows (station IDs, characters, etc.)
   • Single Show: Bump for one show
   • Two Shows: Transitional bump between shows
   • Three Shows: Lineup announcement with three shows

   Fill in Fields (fields change based on type):

   For Generic bumps:

   • Special Name (e.g., "robots", "sara", "clydes")

   For Single Show bumps:

   • Show 1 name
   • Placement (back, to ads, generic, intro, next)

   For Two Shows bumps:

   • Show 1 name
   • Transition type (Next From, From)
   • Show 2 name

   For Three Shows bumps:

   • Show 1, Show 2, Show 3 names
   • Optional: Include "Now" keyword

   Optional Fields (all types):

   • AD Version (numeric identifier like "01", "05")
   • Color (red, blue, green, etc.)

6. Preview Filename

   • Generated filename shows in real-time as you type
   • Green checkmark = valid naming
   • Red X = invalid (with error explanation)

7. Save

   • Click Extract button
   • FFmpeg extracts the segment
   • Bump saved to: {output_folder}/{channel_name}/{generated_filename}.mp4
   • Extraction added to list

8. Continue Extracting

   • Markers automatically clear after extraction
   • Mark next bump and repeat
   • All extractions tracked in session

Managing Extractions

Extraction List (bottom panel):

• Shows all bumps extracted in current session
• Columns: Filename, Start Time, End Time, Duration, Bump Type

Export Session:

• File → Export Session
• Saves extraction history to CSV file

Clear Markers:

• Click Clear Markers to reset start/end points without extracting

Naming Convention Reference

Generic Bumps

[Network] [Version] [Special] [AD_Version]

Example: Toonami 2 0 robots 03.mp4

Single Show Bumps

[Network] [Version] [Show] [Placement] [AD_Version] [Color]

Example: Toonami 2 0 Gundam back 4 red.mp4

Two-Show Bumps

[Network] [Version] [Show1] [Transition] [Show2] [AD_Version] [Color]

Example: Toonami 2 0 Gundam Next From Evangelion 05 blue.mp4

Three-Show Bumps

[Network] [Version] [Now] [Show1] [Next] [Show2] [Later] [Show3] [AD_Version] [Color]

Example: Toonami 2 0 Now Gundam Next Evangelion Later Cowboy Bebop 10 green.mp4

Version Numbers

• 1 0 = Original Toonami (OG)
• 2 0 = Toonami 2.0
• 3 0 = Toonami 3.0
• 7 0 = Custom bumps

Configuration

Changing Settings:

• Edit → Preferences
• Modify channel name or output folder
• Changes saved immediately

Configuration Location:

• macOS/Linux: ~/.bumpextractor/sessions.db
• Windows: %USERPROFILE%\.bumpextractor\sessions.db

Keyboard Shortcuts

• Ctrl+O: Open video file
• Spacebar: Play/pause video

Tips

1. Fast Extraction: Use codec copy mode (default) for instant extraction with no quality loss

2. Precise Marking: Use arrow keys or click timeline at exact timestamps for frame-accurate marks

3. Batch Processing: Extract multiple bumps from one video before closing to keep session organized

4. Check Existing Files: Tool warns if filename already exists before overwriting

5. Session Recovery: If app crashes, session database preserves extraction history

Troubleshooting

"FFmpeg not found" error

• Verify FFmpeg is installed: ffmpeg -version
• Ensure FFmpeg is in system PATH
• Restart terminal/computer after installing FFmpeg

"VLC not found" or video playback issues

• Verify VLC is installed: vlc --version
• macOS: Make sure VLC.app is in /Applications/
• Linux: Install vlc package via package manager
• Windows: Reinstall VLC from https://www.videolan.org/vlc/
• Try restarting the application after installing VLC

Video won't load

• Check file format (supported: mp4, mkv, avi, mov, flv, wmv, m4v, webm)
• Verify file isn't corrupted
• Try opening in VLC or another player first

No audio during playback

• Check system volume settings
• Verify audio works in standalone VLC player
• Try a different video file to rule out file-specific issues

Extraction fails

• Check available disk space
• Verify write permissions to output folder
• Try a shorter segment (some codecs have keyframe issues)
• If codec copy fails, app will automatically retry with re-encoding

Project Structure

bumpextractor/
├── main.py                  # Entry point
├── requirements.txt         # Python dependencies
├── README.md               # This file
├── core/                   # Core functionality
│   ├── Database.py         # SQLite session management
│   ├── VideoProcessor.py   # FFmpeg video operations
│   └── NamingValidator.py  # Filename validation logic
└── GUI/                    # User interface
    ├── BumpExtractor.py    # Main application window
    └── NamingForm.py       # Smart naming dialog

License

https://weebcoders.com/license

Support

For issues, bugs, or feature requests, please create an issue in the project repository or join the WeebCoders discord