Skip to content

Commit 8c8c1e3

Browse files
simoninnssimoninns
authored
Merge pull request #973 from simoninns/readme-2025
Added and amended README.md files for all tools
2 parents 33c267b + 0ee8f3e commit 8c8c1e3

File tree

22 files changed

+2960
-41
lines changed

22 files changed

+2960
-41
lines changed

‎tools/README.md‎

Lines changed: 59 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,65 @@
1-
# ld-decode-tools
2-
ld-decode-tools is a suite of applications for processing the .tbc output from ld-decode. The tools enable various processing of the LaserDisc including VBI, 40-bit FM code, White-Flag, dropout detection/correction and comb filtering. The ld-decode-tools use a JSON based metadata file to store and communicate information about the .tbc. Details of the tools and the JSON metadata format can be found on the ld-decode wiki pages.
1+
# ld-decode Tools
32

3+
This directory contains the complete suite of tools for processing LaserDisc captures and TBC (Time Base Corrected) files. The ld-decode project provides professional-grade tools for digitizing, processing, and analyzing analog video sources with exceptional quality and accuracy.
44

5-
## Software License (GPLv3)
5+
## Tool Categories
66

7-
ld-decode-tools is free software: you can redistribute it and/or modify
8-
it under the terms of the GNU General Public License as published by
9-
the Free Software Foundation, either version 3 of the License, or
10-
(at your option) any later version.
7+
### Core Processing Tools
8+
- **ld-decode** - Primary decoder for raw RF captures to TBC format
9+
- **ld-process-vbi** - Decode Vertical Blanking Interval data
10+
- **ld-process-vits** - Process Vertical Interval Test Signals
11+
- **ld-process-ac3** - Extract Dolby Digital AC3 audio tracks
1112

12-
ld-decode-tools is distributed in the hope that it will be useful,
13-
but WITHOUT ANY WARRANTY; without even the implied warranty of
14-
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15-
GNU General Public License for more details.
13+
### EFM Decoder Suite
14+
*Replaces deprecated ld-process-efm with staged decoding and stacking capabilities*
15+
- **efm-decoder-f2** - Convert EFM T-values to F2 sections
16+
- **efm-decoder-d24** - Convert F2 sections to Data24 format
17+
- **efm-decoder-audio** - Convert EFM Data24 sections to 16-bit stereo PCM audio
18+
- **efm-decoder-data** - Convert EFM Data24 sections to ECMA-130 binary data
19+
- **efm-stacker-f2** - Combine multiple F2 captures for improved quality
1620

17-
You should have received a copy of the GNU General Public License
18-
along with this program. If not, see <http://www.gnu.org/licenses/>.
21+
### Analysis and Quality Tools
22+
- **ld-analyse** - GUI tool for TBC file analysis and visualization
23+
- **ld-discmap** - TBC and VBI alignment and correction tool
24+
- **ld-dropout-correct** - Advanced dropout detection and correction
25+
- **ld-chroma-decoder** - Color decoder for TBC LaserDisc video to RGB/YUV conversion
26+
- **ld-disc-stacker** - Combine multiple TBC captures for improved quality
27+
28+
### Export and Conversion Tools
29+
- **ld-export-metadata** - Export TBC metadata to external formats
30+
- **ld-lds-converter** - Convert between 10-bit and 16-bit LaserDisc sample formats
31+
- **ld-json-converter** - Convert between old internal JSON and new internal SQLite metadata formats
32+
33+
### Utility Scripts
34+
- **ld-compress** - Compress TBC files for storage (in scripts/)
35+
- **filtermaker** - Create custom filtering profiles (in scripts/)
36+
- **tbc-video-export-legacy** - Legacy TBC to video conversion (archived)
37+
38+
## Getting Started
39+
40+
1. **Capture Processing**: Start with `ld-decode` to convert raw RF captures to TBC format
41+
2. **Quality Analysis**: Use `ld-analyse` to assess capture quality and identify issues
42+
3. **Correction**: Apply `ld-dropout-correct` for dropout repair if needed
43+
4. **Chroma Decoding**: Process composite sources with `ld-chroma-decoder`
44+
5. **Export**: Convert to final formats using `tbc-video-export`
45+
46+
## Important Notes
47+
48+
- **SQLite Format**: All tools now use SQLite format for metadata storage instead of JSON
49+
- **File Extensions**: TBC files use `.tbc` extension, metadata uses `.tbc.db` (SQLite format)
50+
- **Dependencies**: Most tools require FFmpeg and other multimedia libraries
51+
- **Performance**: Many tools support multi-threading for faster processing
52+
53+
**⚠️ Important**: The SQLite metadata format is **internal to ld-decode tools only** and subject to change without notice. External tools and scripts should **not** access this database directly. Instead, use `ld-export-metadata` or similar tools to export metadata in stable, documented formats.
54+
55+
## Documentation
56+
57+
Each tool directory contains detailed README.md files with:
58+
- Comprehensive usage instructions
59+
- Complete option references
60+
- Practical examples
61+
- Input/output format specifications
62+
- Troubleshooting guides
63+
64+
See individual tool directories for specific documentation.
1965

‎tools/efm-decoder/README.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# efm-decoder
2+
3+
**EFM Decoder Tools Suite**
4+
5+
## Overview
6+
7+
The efm-decoder suite provides a comprehensive collection of specialized tools for decoding Eight-to-Fourteen Modulation (EFM) encoded digital data from LaserDisc and Compact Disc captures. This modular approach replaces the deprecated single-tool `ld-process-efm` with specialized components that operate at different stages of the EFM decoding pipeline.
8+
9+
## Tool Suite Components
10+
11+
### efm-decoder tool
12+
**EFM to F2 Section Processor** - Converts raw EFM data to synchronized F2 sections
13+
- Input: Raw .efm files from ld-decode
14+
- Output: .f2 section files
15+
- Function: Frame synchronization, deinterleaving, initial error detection
16+
17+
### efm-decoder tool
18+
**F2 Section Multi-Source Stacker** - Combines multiple F2 sources for improved quality
19+
- Input: Multiple .f2 files from same source material
20+
- Output: Enhanced .f2 file
21+
- Function: Majority-vote error correction, multi-capture recovery
22+
23+
### efm-decoder tool
24+
**D24 Data Processor** - Converts F2 sections to D24 format with CIRC error correction
25+
- Input: .f2 section files
26+
- Output: .d24 files with error correction applied
27+
- Function: CIRC decoding, Reed-Solomon error correction, frame validation
28+
29+
### efm-decoder tool
30+
**Audio Stream Decoder** - Extracts PCM audio from D24 data
31+
- Input: .d24 files
32+
- Output: .wav audio files
33+
- Function: Audio deinterleaving, sample reconstruction, format conversion
34+
35+
### efm-decoder tool
36+
**Data Stream Decoder** - Extracts binary data from D24 streams
37+
- Input: .d24 files
38+
- Output: .bin data files
39+
- Function: Data sector extraction, file system recovery, metadata preservation
40+
41+
### efm-decoder tool
42+
**Virtual File System Verifier** - Validates and analyzes recovered data
43+
- Input: .bin data files
44+
- Output: Verification reports and extracted files
45+
- Function: VFS integrity checking, file extraction, quality assessment
46+
47+
## Standard Processing Workflows
48+
49+
### Audio Recovery (CD/LaserDisc Digital Audio)
50+
51+
#### Single-Source Workflow
52+
```bash
53+
# Standard pipeline for digital audio extraction
54+
efm-decoder-f2 capture.efm capture.f2
55+
efm-decoder-d24 capture.f2 capture.d24
56+
efm-decoder-audio capture.d24 final_audio.wav
57+
```
58+
59+
#### Multi-Source Enhanced Recovery
60+
```bash
61+
# Multiple captures for damaged discs
62+
efm-decoder-f2 capture1.efm capture1.f2
63+
efm-decoder-f2 capture2.efm capture2.f2
64+
efm-decoder-f2 capture3.efm capture3.f2
65+
66+
# Stack for improved quality
67+
efm-stacker-f2 capture1.f2 capture2.f2 capture3.f2 stacked.f2
68+
69+
# Continue with enhanced input
70+
efm-decoder-d24 stacked.f2 enhanced.d24
71+
efm-decoder-audio enhanced.d24 recovered_audio.wav
72+
```
73+
74+
### Data Recovery (Domesday LaserDisc, CD-ROM)
75+
76+
#### Standard Data Extraction
77+
```bash
78+
# Pipeline for data disc recovery
79+
efm-decoder-f2 data_capture.efm data.f2
80+
efm-decoder-d24 data.f2 data.d24
81+
efm-decoder-data data.d24 recovered_data.bin --output-metadata data_info.txt
82+
```
83+
84+
#### Complete Domesday Recovery with Verification
85+
```bash
86+
# Multi-source Domesday disc recovery
87+
efm-decoder-f2 domesday1.efm dom1.f2
88+
efm-decoder-f2 domesday2.efm dom2.f2
89+
efm-decoder-f2 domesday3.efm dom3.f2
90+
91+
# Stack multiple sources
92+
efm-stacker-f2 dom1.f2 dom2.f2 dom3.f2 domesday_stacked.f2
93+
94+
# Process to final data
95+
efm-decoder-d24 domesday_stacked.f2 domesday.d24
96+
efm-decoder-data domesday.d24 domesday.bin --output-metadata domesday_meta.txt
97+
98+
# Verify and extract VFS content
99+
vfs-verifier domesday.bin domesday_report.txt \
100+
--vfs-type domesday \
101+
--extract-files \
102+
--verify-checksums \
103+
--output-dir domesday_extracted
104+
```
105+
106+
## Pipeline Architecture
107+
108+
### EFM Decoding Stages
109+
110+
The EFM decoding process involves multiple clearly defined stages:
111+
112+
```
113+
Raw EFM Data → F2 Sections → D24 Data → Audio/Data Output
114+
↓ ↓ ↓ ↓
115+
efm-decoder-f2 [stacking] efm-decoder-d24 decoder-audio/data
116+
↓
117+
efm-stacker-f2
118+
```
119+
120+
### Stage Descriptions
121+
122+
1. **Raw EFM (.efm)** - Output from ld-decode containing synchronized EFM bitstream
123+
2. **F2 Sections (.f2)** - Deinterleaved 98-frame sections with sync and error detection
124+
3. **D24 Data (.d24)** - CIRC error-corrected data ready for final decoding
125+
4. **Final Output** - PCM audio (.wav) or binary data (.bin) with optional verification
126+
127+
### Multi-Source Enhancement
128+
129+
The pipeline supports multi-source stacking at the F2 level:
130+
- Capture same material multiple times with different equipment/settings
131+
- Combine sources using majority-vote error correction
132+
- Dramatically improves recovery of damaged or degraded media
133+
- Particularly effective for archive-quality Domesday LaserDisc recovery
134+
135+
## Advanced Features
136+
137+
### Pipelining Capabilities
138+
- **Streaming Processing**: Tools can process data in chunks for memory efficiency
139+
- **Parallel Sources**: Multiple captures can be processed simultaneously
140+
- **Quality Assessment**: Each stage provides error statistics and quality metrics
141+
- **Format Flexibility**: Support for both audio and data applications
142+
143+
### Error Correction Hierarchy
144+
1. **Hardware Level**: ld-decode RF signal recovery
145+
2. **EFM Level**: efm-decoder-f2 frame sync and validation
146+
3. **Multi-Source**: efm-stacker-f2 voting correction
147+
4. **CIRC Level**: efm-decoder-d24 Reed-Solomon correction
148+
5. **Application Level**: Format-specific validation (vfs-verifier)
149+
150+
### Quality Enhancement Strategies
151+
- **Multiple Captures**: Different hardware, settings, environmental conditions
152+
- **Temporal Diversity**: Captures at different times for aging media
153+
- **Hardware Diversity**: Different laser assemblies, tracking mechanisms
154+
- **Parameter Tuning**: Optimized settings per capture session
155+
156+
## Performance and Scalability
157+
158+
### Processing Requirements
159+
- **CPU**: Multi-threaded processing for Reed-Solomon operations
160+
- **Memory**: Scales with source count for stacking operations
161+
- **Storage**: Intermediate files require 2-3x source data size
162+
- **Time**: Real-time processing possible for single sources
163+
164+
### Optimization Strategies
165+
- **Chunked Processing**: Handle large files without memory constraints
166+
- **Parallel Decode**: Process multiple sources simultaneously
167+
- **Progressive Enhancement**: Start with best single source, add others as available
168+
- **Quality-Based Selection**: Automatically select optimal source combinations
169+
170+
## Technical Background
171+
172+
### Eight-to-Fourteen Modulation (EFM)
173+
- **Purpose**: Channel coding for optical storage reliability
174+
- **Encoding**: 8-bit data → 14-bit channel patterns + 3 merge bits
175+
- **Benefits**: DC-free signal, clock recovery, minimum transition density
176+
- **Constraints**: Run-length limits (3-11 transitions), spectral shaping
177+
178+
### Cross-Interleaved Reed-Solomon Code (CIRC)
179+
- **C1 Code**: (32,28) RS code, corrects random errors
180+
- **C2 Code**: (28,24) RS code, corrects burst errors
181+
- **Interleaving**: 108-frame delay spread, 4000+ bit burst correction
182+
- **Integration**: Works with EFM constraints and optical tracking
183+
184+
### Frame Structure and Timing
185+
- **F3 Frames**: 588 channel bits, 1/7350 second duration
186+
- **F2 Sections**: 98 F3 frames, 1/75 second (sector timing)
187+
- **Synchronization**: 24-bit sync pattern + frame validation
188+
- **Data Capacity**: 24 bytes user data + 8 bytes error correction per frame
189+
190+
191+

0 commit comments

Comments
 (0)