Repository navigation
File Naming Conventions
Proper file naming is crucial for CommercialBreaker & Toonami Tools to work correctly. This guide outlines the exact naming schemes required for episodes and bumps.
[SHOW_TITLE] - S[SEASON_NUMBER]E[EPISODE_NUMBER] - [OPTIONAL_DESCRIPTION]
- Show title followed by space, hyphen, space
- Season: Always two digits (S01, S02, etc.)
- Episode: Always two digits (E01, E28, etc.)
- Description: Everything after the second hyphen is optional
✅ Correct naming:
Naruto - S01E28 - Eat or Be Eaten - Panic in the Forest Bluray-1080p Remux.mkv
One Piece - S11E01 - Marine High Admiral Aokiji! The Threat of the Greatest Power.mp4
Bleach - S02E15 - Ishida's Strategy! The 20-second Offense and Defense.mkv
Cowboy Bebop - S01E01 - Asteroid Blues.mkv
❌ Incorrect naming:
Naruto S01E28.mkv # Missing hyphens and spaces
Naruto-S1E28.mkv # Wrong separator, single digit season
One Piece S11 E01.mkv # Inconsistent spacing
Bleach_S02E15.mkv # Underscores instead of hyphens
- Deviations from this scheme will cause episodes to be ignored
- The system uses this pattern for regex matching
- File extensions can be any video format (.mkv, .mp4, .avi, etc.)
- Optional description can include quality info, release groups, etc.
Bump naming is more complex as it varies based on the number of shows involved in each bump.
- Maintain spaces between each component (underscores are acceptable if consistent)
- Components like AD_VERSION or COLOR might not always be necessary
- All bumps must follow these schemes or they won't be used
- Multi-show bumps use different patterns based on show count
Network: The network name configured in config.network
- Standard: "Toonami" (default)
- Networkless Mode: "Networkless" - bypasses Wikipedia validation, allows any custom content
- Other Networks: "Cartoon Network", "Adult Swim", etc. (must have Wikipedia broadcast list page)
Toonami Version: The era/version with space replacing the period
-
1 0= Original Toonami (OG) -
2 0= Toonami 2.0 -
3 0= Toonami 3.0 -
7 0= Custom bumps (recommended for user-created content) - Missing version defaults to
1 0(OG)
Important: When using Networkless mode (config.network = "Networkless"), all bump filenames must use "Networkless" as the network prefix instead of "Toonami". See examples below.
Pattern: [Network] [TOONAMI_VERSION] [SPECIAL_SHOW_NAME] [AD_VERSION]
Examples:
Toonami 2 0 robots 03.mp4
Toonami 3 0 clydes 04.mp4
Toonami 2 0 sara 01.mp4
Networkless Examples:
Networkless 2 0 robots 03.mp4
Networkless 3 0 clydes 04.mp4
Networkless 7 0 sara 01.mp4
Use: General bumps, character appearances, station IDs
Pattern: [Network] [TOONAMI_VERSION] [SHOW_NAME] [PLACEMENT] [AD_VERSION] [COLOR]
Placement Options:
-
back- "We'll be right back" -
to ads- Going to commercial -
generic- General show bump -
intro- Show introduction -
next- "Coming up next"
Examples:
Toonami 2 0 Gundam back 4 red.mp4
Toonami 2 0 Gundam to ads 05 blue.mp4
Toonami 2 0 Gundam generic 09.mp4
Toonami 2 0 Gundam intro.mp4
Toonami 2 0 Gundam next 12 purple.mp4
Networkless Examples:
Networkless 2 0 Gundam back 4 red.mp4
Networkless 2 0 Naruto to ads 05 blue.mp4
Networkless 7 0 One Piece intro.mp4
Pattern: [Network] [TOONAMI_VERSION] [SHOW_1] [TRANSITION] [SHOW_2] [AD_VERSION] [COLOR]
Transition Options:
-
Next From- "Next from [Show 1] to [Show 2]" -
From- "From [Show 1] to [Show 2]"
Examples:
Toonami 2 0 Gundam Next From Evangelion 05 blue.mp4
Toonami 2 0 Inuyasha From Evangelion 7 blue.mp4
Toonami 3 0 Naruto Next From Bleach 02.mp4
Networkless Examples:
Networkless 2 0 Gundam Next From Evangelion 05 blue.mp4
Networkless 3 0 Naruto From Bleach 02.mp4
Pattern: [Network] [TOONAMI_VERSION] [NOW] [SHOW_1] [NEXT] [SHOW_2] [LATER] [SHOW_3] [AD_VERSION] [COLOR]
Keywords:
-
Now- Optional opener -
Next- Required between shows -
Later- Required before final show
Examples:
Toonami 2 0 Now Gundam Next Evangelion Later Cowboy Bebop 10 green.mp4
Toonami 3 0 Now Inuyasha Next Bleach Later Naruto 2.mp4
Toonami 2 0 Gundam Next Evangelion Later Cowboy Bebop 05.mp4
Networkless Examples:
Networkless 2 0 Now Gundam Next Evangelion Later Cowboy Bebop 10 green.mp4
Networkless 7 0 Now Naruto Next Bleach Later One Piece 05.mp4
| Component | Description | Examples |
|---|---|---|
| Network | Network from config.network
|
Toonami, Networkless, Cartoon Network
|
| Version | Era with space for period |
2 0, 3 0, 7 0
|
| Show Name | Exact show name |
Gundam, Naruto, One Piece
|
| Component | Description | Examples |
|---|---|---|
| AD_VERSION | Numeric identifier |
01, 05, 12
|
| COLOR | Thematic categorization |
red, blue, green
|
| PLACEMENT | Single show context |
back, intro, next
|
| Type | Keywords | Usage |
|---|---|---|
| Single |
back, to ads, generic, intro, next
|
Show-specific context |
| Double |
Next From, From
|
Between two shows |
| Triple |
Now, Next, Later
|
Three-show lineup |
❌ Missing spaces around hyphens
Naruto-S01E01-Title.mkv
✅ Correct spacing
Naruto - S01E01 - Title.mkv
❌ Single digit season/episode
Naruto - S1E1 - Title.mkv
✅ Two digit format
Naruto - S01E01 - Title.mkv
❌ Missing version
Toonami Gundam back.mp4
✅ Include version
Toonami 2 0 Gundam back.mp4
❌ Wrong transition keywords
Toonami 2 0 Gundam to Evangelion.mp4
✅ Correct transition
Toonami 2 0 Gundam Next From Evangelion.mp4
Some shows have common abbreviations that the system recognizes eg:
| Full Name | Acceptable Variations |
|---|---|
| Fullmetal Alchemist Brotherhood |
fmab, FMAB
|
| Dragon Ball Z |
dbz, DBZ
|
-
Check episode naming: Use regex pattern
^.+ - S\d{2}E\d{2} - .+$ - Verify bump structure: Ensure correct component order
- Test with samples: Process a few files first
- Use consistent formatting: Don't mix underscores and spaces
- Bulk rename utilities: PowerRename (Windows), Name Mangler (Mac)
- Regex tools: Test naming patterns before batch operations
- File organization: Group by naming scheme compliance
Use Toonami version 7 0 for user-created bumps:
Toonami 7 0 Custom Show back 01.mp4
- AD_VERSION can be omitted for unique bumps
- COLOR is always optional
- Version defaults to
1 0if missing
If you have multiple versions of the same bump:
Toonami 2 0 Gundam back 01 red.mp4
Toonami 2 0 Gundam back 02 red.mp4
Toonami 2 0 Gundam back 03 blue.mp4
- Check for exact spacing:
- S##E## - - Verify two-digit season/episode numbers
- Ensure no extra characters in critical positions
- Validate component order matches patterns above
- Check for typos in show names
- Ensure proper spacing between components
- Verify Toonami version format
- Use exact names as they appear in your anime library
- Check for common abbreviations in the code
- Consider adding custom mappings if needed
CommercialBreaker uses a centralized FilenameParser utility for consistent episode filename parsing across all modules.
Module: ToonamiTools/utils/FilenameParser.py
Why FilenameParser Exists:
- Provides single source of truth for filename parsing
- Ensures consistent behavior across all modules
- Easier to maintain and test than duplicate parsing logic
Automatic Year Handling:
# Automatically strips release years from show names
"Naruto (2002) - S01E05 - Title.mkv" → Show: "Naruto"
"Attack on Titan (2013) - S01E01.mkv" → Show: "Attack on Titan"Comprehensive SxxExx Extraction:
- Handles both uppercase and lowercase (S01E05, s01e05)
- Supports single and double-digit seasons/episodes
- Validates format correctness
Show Name Normalization:
- Removes release years in parentheses
- Trims whitespace
- Validates show name is not empty
from ToonamiTools.utils.FilenameParser import FilenameParser
parser = FilenameParser()
# Parse episode filename
result = parser.parse_episode_filename("Naruto (2002) - S01E05 - Episode Title.mkv")
# Returns:
{
'show': 'Naruto', # Year stripped automatically
'season': '01', # Always two digits
'episode': '05', # Always two digits
'full_pattern': 'S01E05', # Original pattern
'description': 'Episode Title' # Optional description
}
# Invalid filename returns None
result = parser.parse_episode_filename("Invalid Filename.mkv")
# Returns: NoneCore Processing:
-
VirtualCut.py- Cutless mode operations -
DirectoryScanner.py- File discovery and organization -
BlockMaker.py- BLOCK_ID generation
Platform Integration:
-
PlexToDizqueTV.py- Channel creation -
PlexToTunarr.py- Channel creation
Validation System:
- All 20 validators use FilenameParser for consistency checks
- Ensures validators detect same patterns as main tools
FilenameParser validates:
- Pattern Presence: SxxExx must exist in filename
- Format Correctness: Season and episode must be two digits
- Show Name: Must exist and be non-empty after extraction
- No Ambiguity: Only one SxxExx pattern per filename
Example Validation:
✅ "Naruto - S01E05 - Title.mkv" # Valid
✅ "Naruto (2002) - S01E05.mkv" # Valid (year stripped)
❌ "Naruto S01E05.mkv" # Invalid (missing hyphens)
❌ "Naruto - S1E5 - Title.mkv" # Invalid (single digits)
❌ "Movie - Title.mkv" # Invalid (no pattern)Consistency:
- Same parsing logic everywhere
- Predictable behavior across all tools
- No "works here but not there" issues
Reliability:
- Comprehensive validation catches malformed names
- Clear error messages when parsing fails
- Prevents silent failures
Maintainability:
- Single place to fix bugs or update logic
- All modules benefit from improvements
- Easier to add new features
Automatic During:
- Content discovery (scanning anime folders)
- Episode filtering (separating bumps from anime)
- Virtual cutting (cutless mode filename handling)
- BLOCK_ID generation (show name extraction)
- Channel creation (episode organization)
- Validation (all 20 validators)
You Don't Call It Directly:
- FilenameParser is used internally by the application
- Just ensure your files follow naming conventions
- System handles parsing automatically
When FilenameParser detects issues:
- S.A.R.A. validation shows which files failed parsing
- Error messages indicate which naming rule violated
- Suggestions provided for fixing filenames
Example S.A.R.A. Output:
[WARNING] ToonamiChecker → Toonami_Episodes
Message: 3 episode(s) have non-standard naming
Details: Expected format: [SHOW] - S##E## - [title].ext
Files affected:
• /anime/Naruto S01E05.mkv (missing hyphens)
• /anime/One Piece - S1E1.mkv (single digit season/episode)
• /anime/Bleach_S02E15.mkv (underscores instead of hyphens)
Suggestion: Rename files to match required format. Use batch renaming tools if needed.
Need help with naming? Check the FAQ for additional examples and solutions, or join our Discord community for assistance.