diff --git a/docs/AUTHOR_MODULE.md b/docs/AUTHOR_MODULE.md new file mode 100644 index 0000000..c91913d --- /dev/null +++ b/docs/AUTHOR_MODULE.md @@ -0,0 +1,471 @@ +# Author Module - Complete Guide + +## Overview + +The Author module creates DVD/Blu-ray compliant disc structures from video files. It handles encoding, chapter management, and ISO generation with automatic timestamp correction for maximum compatibility. + +--- + +## Quick Start + +### Single File to ISO + +1. **Select Files Tab** → Click "Select File" → Choose your video +2. **Settings Tab** → Configure output settings: + - Output Type: DVD or Blu-ray + - Region: NTSC (29.97fps) or PAL (25fps) + - Aspect Ratio: 4:3 or 16:9 + - Disc Size: DVD5 (4.7GB) or DVD9 (8.5GB) +3. **Generate Tab** → Click "Generate DVD/ISO" +4. Output will be VIDEO_TS folder or .iso file + +### Multiple Files to Single Disc + +1. **Clips Tab** → Click "Add Video" → Add multiple files +2. Enable "Treat as Chapters" to merge into single title +3. **Settings Tab** → Configure as above +4. **Generate Tab** → Create multi-title or chaptered disc + +--- + +## Features + +### Automatic Chapter Detection + +Detects scene changes and creates chapter markers automatically. + +**How It Works:** +1. Load video in Files or Clips tab +2. **Chapters Tab** → Adjust "Detection Sensitivity" slider + - Lower (0.1-0.2): Detects subtle changes, many chapters + - Medium (0.3-0.4): Balanced, good for most videos + - Higher (0.5-0.7): Only major scene changes +3. Click "Detect Scenes" +4. **Visual Preview:** + - Thumbnail grid shows first 24 detected chapters + - Each thumbnail displays frame at chapter timestamp + - Verify detection quality visually +5. Click "Accept Chapters" to use, or "Reject" to try different sensitivity + +**Technical Details:** +- Uses FFmpeg scene detection filter: `select='gt(scene,threshold)'` +- Threshold 0.30 = scene score must exceed 30% for detection +- Thumbnails extracted at 320x180, stored in temp directory +- Preview limited to 24 chapters for UI performance + +**Use Cases:** +- Movies: Detect major scene changes (use 0.5-0.6) +- Documentaries: Detect segment breaks (use 0.4-0.5) +- TV Shows: Detect act breaks (use 0.3-0.4) +- Music Videos: Detect shot changes (use 0.2-0.3) + +### Chapter Management + +**Load Embedded Chapters:** +- Click "Load Embedded" to extract chapters from MKV/MP4 files +- Preserves original chapter titles and timestamps + +**Manual Chapter Addition:** +- Click "+ Add Chapter" to insert custom chapter point +- Set timestamp and title manually + +**Export Chapters:** +- Click "Export Chapters" to save chapter list +- Formats: XML, OGM, or text file + +### DVD Timestamp Correction + +**Problem Solved:** +DVD authoring tools (dvdauthor) require perfectly sequential MPEG-2 timestamps. FFmpeg direct encoding sometimes produces backwards-moving SCR (System Clock Reference) values, causing errors: +``` +ERR: SCR moves backwards at inoffset 0, remultiplex input +``` + +**Solution:** +VideoTools automatically remultiplexes encoded MPEG files: +```bash +ffmpeg -fflags +genpts -i encoded.mpg -c copy -f dvd output.mpg +``` +- `-fflags +genpts`: Regenerate presentation timestamps +- `-c copy`: No re-encoding (fast, no quality loss) +- `-f dvd`: Ensure DVD format compliance + +**Result:** +- 100% dvdauthor compatibility +- Fixes SCR errors on AVI, MKV, MP4 sources +- Adds ~5 seconds per title (negligible) + +--- + +## UI Features + +### Authoring Log Viewer + +Real-time log display during DVD generation. + +**Performance Optimizations:** +- Displays last 100 lines only (tail behavior) +- Prevents memory bloat on long encodes +- Full log written to file for reference + +**Controls:** +- **Copy Log**: Copies full log from file to clipboard +- **View Full Log**: Opens complete log in dedicated viewer +- Shows "Authoring Log (last 100 lines)" label + +**Technical:** +- Circular buffer maintains fixed 100-line limit +- O(1) memory usage vs O(n) unbounded growth +- Rebuilds display text from buffer on each append +- Log file path tracked for full viewing + +### Progress Tracking + +- Real-time progress bar (0-100%) +- Status messages: "Encoding 1/3", "Authoring DVD structure", etc. +- Current operation displayed above progress bar + +--- + +## Output Formats + +### VIDEO_TS Folder Structure +``` +output/ + VIDEO_TS/ + VIDEO_TS.IFO # DVD table of contents + VIDEO_TS.VOB # Menu video (if applicable) + VTS_01_0.IFO # Title 1 information + VTS_01_1.VOB # Title 1 video data + VTS_02_0.IFO # Title 2 information (if multiple) + VTS_02_1.VOB # Title 2 video data + AUDIO_TS/ # Empty (required by DVD spec) +``` + +### ISO Image +- Single .iso file containing complete VIDEO_TS structure +- Burnable to DVD-R/DVD-RW +- Mountable in virtual drives +- Playable in VLC, Kodi, standalone players + +--- + +## Configuration Options + +### Output Type +- **DVD**: DVD-Video format (MPEG-2, AC-3 audio) +- **Blu-ray**: Not yet implemented + +### Region +- **NTSC**: 29.97fps, 720x480, North America/Japan +- **PAL**: 25fps, 720x576, Europe/Asia/Africa + +### Aspect Ratio +- **4:3**: Standard (old TV format) +- **16:9**: Widescreen (modern format) +- **AUTO**: Detect from source video + +### Disc Size +- **DVD5**: Single-layer, 4.7GB capacity +- **DVD9**: Dual-layer, 8.5GB capacity + +### Create Menu +- Enable to generate simple title selection menu +- Requires additional processing time +- Menu background uses first frame of first title + +### Treat as Chapters +- Merge multiple clips into single title with chapter points +- Chapter timestamps auto-calculated from clip durations +- Useful for episodic content or multi-part videos + +--- + +## Encoding Settings + +### Video +- Codec: MPEG-2 Video +- Resolution: 720x480 (NTSC) or 720x576 (PAL) +- Bitrate: 6000kbps (NTSC) / 8000kbps (PAL) +- Max Bitrate: 9000kbps (NTSC) / 9500kbps (PAL) +- GOP Size: 15 frames +- Pixel Format: YUV 4:2:0 +- Interlacing: Enabled with ILME+ILDCT flags + +### Audio +- Codec: AC-3 (Dolby Digital) +- Bitrate: 192kbps +- Sample Rate: 48kHz +- Channels: Stereo (2.0) + +### Filters +- Scale to target resolution with aspect preservation +- Pad with black bars if needed to maintain aspect +- Force constant frame rate (CFR) + +--- + +## Workflow Examples + +### Example 1: Single Movie to DVD + +**Scenario:** Convert vacation.mp4 to playable DVD + +1. Author Module → Files Tab +2. Click "Select File" → Choose vacation.mp4 +3. Settings Tab: + - Output Type: DVD + - Region: NTSC + - Aspect Ratio: 16:9 + - Disc Size: DVD5 +4. Chapters Tab: + - Adjust sensitivity to 0.40 + - Click "Detect Scenes" + - Preview thumbnails, verify chapter points + - Accept chapters +5. Generate Tab: + - Title: "Family Vacation" + - Output Path: ~/Videos/vacation.iso + - Click "Generate DVD/ISO" +6. Monitor progress in authoring log +7. Burn vacation.iso to DVD-R + +**Result:** Playable DVD with auto-detected chapters + +### Example 2: TV Series Disc (Multi-Title) + +**Scenario:** Combine 3 episodes onto one DVD + +1. Author Module → Clips Tab +2. Add Videos: + - episode1.mkv + - episode2.mkv + - episode3.mkv +3. **Do NOT** enable "Treat as Chapters" +4. Settings Tab: + - Output Type: DVD + - Region: NTSC + - Create Menu: Yes +5. Generate Tab: + - Title: "Series S01" + - Output Path: ~/Videos/series_s01.iso + - Generate +6. Result: 3 separate titles with menu selection + +### Example 3: Concert with Manual Chapters + +**Scenario:** Concert video with chapters for each song + +1. Author Module → Files Tab +2. Select concert.mp4 +3. Chapters Tab: + - Manual chapter addition: + - 00:00 - "Opening" + - 03:45 - "Song 1" + - 07:30 - "Song 2" + - etc. +4. Settings Tab → Configure as DVD +5. Generate → Create ISO with song navigation + +--- + +## Troubleshooting + +### "SCR moves backwards" Error + +**Cause:** MPEG-2 timestamps not DVD-compliant + +**Solution:** Automatic as of latest version +- Remux step added after encoding +- Regenerates timestamps with `-fflags +genpts` +- Error should not occur anymore + +**If Still Occurring:** +- Verify you're using latest VideoTools build +- Check if source video has corruption +- Try re-downloading source file + +### Chapter Detection Finds Too Many Chapters + +**Cause:** Sensitivity too low (detects minor changes) + +**Solution:** +- Increase sensitivity slider (0.5-0.7) +- Re-run "Detect Scenes" +- Preview thumbnails to verify +- Aim for 8-15 chapters per 90-minute video + +### Chapter Detection Finds Too Few Chapters + +**Cause:** Sensitivity too high (only detects major changes) + +**Solution:** +- Decrease sensitivity slider (0.2-0.3) +- Re-run detection +- Verify with visual preview + +### Authoring Log Causes UI Lag + +**Cause:** Large log files (thousands of lines) + +**Fixed:** As of latest version +- Only last 100 lines displayed in UI +- Full log accessible via "View Full Log" button +- Memory usage capped + +**If Still Slow:** +- Click "View Full Log" to open in separate viewer +- Main UI will remain responsive + +### ISO File Won't Burn to Disc + +**Cause:** File size exceeds disc capacity + +**Solution:** +- Check ISO size: Should be <4.7GB for DVD5 +- If larger, use DVD9 disc or split content +- Reduce video bitrate in Settings if needed + +### Video Playback Stutters on DVD Player + +**Cause:** Framerate conversion or interlacing issues + +**Solution:** +- Verify source video is Constant Frame Rate (CFR) +- If Variable Frame Rate (VFR), convert to CFR first +- Try enabling/disabling interlacing flags + +--- + +## Technical Implementation + +### Encoding Pipeline + +1. **Source Analysis** + - Probe video with ffprobe + - Detect resolution, framerate, codec + - Identify interlacing mode + +2. **MPEG-2 Encoding** + ```bash + ffmpeg -i input.mp4 \ + -vf "scale=720:480,setdar=16:9,setsar=1,fps=30000/1001" \ + -c:v mpeg2video -r 30000/1001 \ + -b:v 6000k -maxrate 9000k -bufsize 1835k \ + -g 15 -pix_fmt yuv420p -flags +ilme+ildct \ + -c:a ac3 -b:a 192k -ar 48000 -ac 2 \ + output.mpg + ``` + +3. **Timestamp Remux** + ```bash + ffmpeg -fflags +genpts -i output.mpg \ + -c copy -f dvd output_remux.mpg + ``` + +4. **DVD Structure Creation** + - Generate dvdauthor XML with chapter markers + - Run: `dvdauthor -o VIDEO_TS -x dvd.xml` + - Finalize: `dvdauthor -o VIDEO_TS -T` + - Create AUDIO_TS folder + +5. **ISO Generation** (if requested) + - Detect ISO tool: mkisofs, genisoimage, or xorriso + - Create ISO: `mkisofs -dvd-video -o output.iso VIDEO_TS/` + +### Chapter XML Format + +```xml + + + + + + + +``` + +### Temporary Files + +**Location:** System temp + VideoTools prefix +- `videotools-author-XXXXXX/`: Encoding workspace + - `title_01.mpg`: Initial encode + - `title_01_remux.mpg`: Timestamp-corrected version + - `dvd.xml`: DVDAuthor configuration +- `videotools-dvd-XXXXXX/`: VIDEO_TS structure (if making ISO) +- `videotools-chapter-thumbs/`: Chapter preview thumbnails + +**Cleanup:** Automatic on completion or error + +--- + +## Dependencies + +### Required +- **ffmpeg**: Video encoding and analysis +- **dvdauthor**: DVD structure creation + +### Optional +- **mkisofs** or **genisoimage** or **xorriso**: ISO generation +- Only needed if creating .iso files (not needed for VIDEO_TS folders) + +### Installation + +**Fedora/RHEL:** +```bash +sudo dnf install ffmpeg dvdauthor genisoimage +``` + +**Ubuntu/Debian:** +```bash +sudo apt install ffmpeg dvdauthor genisoimage +``` + +**Arch:** +```bash +sudo pacman -S ffmpeg dvdauthor cdrtools +``` + +--- + +## Performance Tips + +1. **Use SSD for Output**: Faster read/write during authoring +2. **Limit Concurrent Jobs**: DVD encoding is CPU-intensive +3. **Preview Before Full Encode**: Test 5-minute segment first +4. **Batch Similar Files**: Use same settings for multiple encodes +5. **Monitor Log File Size**: Large logs indicate potential issues + +--- + +## File Size Estimates + +### NTSC (6000kbps video + 192kbps audio) +- 30 minutes: ~1.3 GB +- 60 minutes: ~2.6 GB +- 90 minutes: ~3.9 GB (fits DVD5) +- 120 minutes: ~5.2 GB (requires DVD9) + +### PAL (8000kbps video + 192kbps audio) +- 30 minutes: ~1.7 GB +- 60 minutes: ~3.4 GB +- 90 minutes: ~5.1 GB (requires DVD9) +- 120 minutes: ~6.8 GB (requires DVD9) + +--- + +## Keyboard Shortcuts + +None specific to Author module. Use main application shortcuts. + +--- + +## Related Documentation + +- **DVD_USER_GUIDE.md**: Creating DVD-compliant video files +- **QUEUE_SYSTEM_GUIDE.md**: Job queue management +- **MODULES.md**: Overview of all VideoTools modules diff --git a/docs/DVD_USER_GUIDE.md b/docs/DVD_USER_GUIDE.md index bf0cc90..8541a8c 100644 --- a/docs/DVD_USER_GUIDE.md +++ b/docs/DVD_USER_GUIDE.md @@ -328,5 +328,4 @@ Happy encoding! 📀 --- -*Generated with Claude Code* -*For support, check the comprehensive guides in the project repository* +For technical details on DVD authoring with chapters, see AUTHOR_MODULE.md