VideoTools/docs/AUTHOR_MODULE.md

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:

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

   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

   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

<dvdauthor>
  <vmgm />
  <titleset>
    <titles>
      <video format="ntsc" aspect="16:9" />
      <pgc>
        <vob file="title_01.mpg" chapters="0:00,3:45.5,7:30.2" />
      </pgc>
    </titles>
  </titleset>
</dvdauthor>

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:

sudo dnf install ffmpeg dvdauthor genisoimage

Ubuntu/Debian:

sudo apt install ffmpeg dvdauthor genisoimage

Arch:

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