Add comprehensive Author module documentation
Created AUTHOR_MODULE.md covering all features in detail: Chapter Detection: - How scene detection works (FFmpeg filter threshold) - Sensitivity slider guide (0.1-0.9 range explained) - Visual preview feature with thumbnails - Use cases for different video types - Technical implementation details DVD Timestamp Correction: - SCR backwards error explanation - Automatic remux solution (-fflags +genpts) - Why it's needed and how it works - Performance impact (negligible) Authoring Log Viewer: - Tail behavior (last 100 lines) - Performance optimizations explained - Copy Log and View Full Log buttons - Memory usage improvements (O(1) vs O(n)) Complete Workflows: - Single movie to DVD - TV series multi-title disc - Concert with manual chapters Troubleshooting: - SCR errors - Too many/few chapters detected - UI lag issues (now fixed) - ISO burning problems - Playback stuttering Technical Details: - Full encoding pipeline with commands - Chapter XML format - Temporary file locations - Dependencies and installation - File size estimates for NTSC/PAL Also updated DVD_USER_GUIDE.md: - Removed branding footer - Added reference to AUTHOR_MODULE.md for technical details
This commit is contained in:
parent
0d1235d867
commit
230523c737
471
docs/AUTHOR_MODULE.md
Normal file
471
docs/AUTHOR_MODULE.md
Normal file
|
|
@ -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
|
||||
<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:**
|
||||
```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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user