### DVPlay CLI Example - Merging and Visualizing Input Files

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/analysis.md

Demonstrates a complex usage of the dvplay command to visualize the relationship between multiple input DV files and a merged output file. This requires specifying lists of input files, their corresponding offsets, and the output file.

```bash
dvplay -s 'file1.dv|file2.dv' -S '120000|240000' -b 240000 output.dv
```

--------------------------------

### Install DVRescue via Homebrew

Source: https://context7.com/mipops/dvrescue/llms.txt

Commands to install the DVRescue suite on macOS or Linux using the Homebrew package manager.

```bash
brew tap mediaarea/homebrew-mediaarea
brew install dvrescue
brew update
brew upgrade dvrescue
```

--------------------------------

### Configure DVRescue Verbosity Levels

Source: https://context7.com/mipops/dvrescue/llms.txt

Examples of how to set different verbosity levels for DVRescue output, ranging from silent to full per-frame analysis.

```bash
dvrescue -v 0 video.dv
dvrescue -v 5 video.dv
dvrescue -v 7 video.dv
dvrescue -v 9 video.dv
```

--------------------------------

### View dvpackager help documentation

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/packaging.md

Displays the full list of available flags and configuration options for the dvpackager tool.

```bash
dvrescue -h
```

--------------------------------

### DVRescue XML Schema Definition

Source: https://context7.com/mipops/dvrescue/llms.txt

An example of the XML structure generated by DVRescue. It includes metadata for frames, timecodes, recording timestamps, and error concealment information.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<dvrescue xmlns="https://mediaarea.net/dvrescue" version="1.2.1">
  <creator>
    <program>dvrescue</program>
    <version>24.07</version>
    <library version="24.06">MediaInfoLib</library>
  </creator>
  <media ref="/path/to/video.dv" format="DV" size="144000000">
    <frames count="900" pts="00:00:00.000000" end_pts="00:00:30.000000"
            size="720x480" video_rate="30000/1001"
            chroma_subsampling="4:1:1" aspect_ratio="4/3"
            audio_rate="48000" channels="2">
      <frame n="0" pos="0" pts="00:00:00.000000"
             tc="01:00:00:00" rdt="2024-01-15 14:30:00"
             rec_start="1"/>
      <frame n="150" pos="18000000" pts="00:00:05.005005"
             tc="01:00:05:00">
        <sta t="2" n="3" n_even="2"/>
        <dseq n="0">
          <sta t="2" n="3" n_even="2"/>
        </dseq>
      </frame>
      <frame n="300" pos="36000000" pts="00:00:10.010010"
             tc="02:00:00:00" tc_nc="1"/>
      <frame n="450" pos="54000000" pts="00:00:15.015015"
             tc="02:00:05:00" rdt="2024-01-16 09:00:00" rdt_nc="1"/>
    </frames>
  </media>
</dvrescue>
```

--------------------------------

### DVPlay CLI Help - Basic Usage

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/analysis.md

Displays the basic syntax for the dvplay command and how to access its help menu. This command is used to visually display errors in DV files and generate associated XML and sidecar files.

```bash
dvplay [options] file.dv
dvplay -h
```

--------------------------------

### DVPlay CLI Options for Analysis and Output

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/analysis.md

Lists and explains various flags and options for the dvplay command. These options control the display mode, output format (XML, JPG, GIF), output location, frame selection by byte offset or timestamp, and the ability to specify custom paths for external tools like ffmpeg and mediainfo.

```bash
dvplay -m
dvplay -x
dvplay -g
dvplay -o OUTPUT
dvplay -O FILE
dvplay -b OFFSET
dvplay -t PTS
dvplay -h
dvplay -B BLOCKS
dvplay -F <path>
dvplay -M <path>
dvplay -D <path>
dvplay -X <path>
dvplay -d <path>
dvplay -s <list>
dvplay -S <list>
dvplay -z
```

--------------------------------

### DV Tape Capture Workflow

Source: https://context7.com/mipops/dvrescue/llms.txt

A complete command-line workflow for capturing DV tapes, including device detection, multi-pass capture, merging, and analysis.

```bash
dvrescue --list_devices
dvrescue --status device://0x800460104ce2bad
dvrescue --cmd rew device://0x800460104ce2bad
dvrescue --cmd play device://0x800460104ce2bad
dvrescue --cmd stop device://0x800460104ce2bad
dvrescue device://0x800460104ce2bad -y --rewind-count 3 -m tape001_pass1.dv -m - | ffplay -
dvrescue device://0x800460104ce2bad -y --rewind-count 3 -m tape001_pass2.dv -m - | ffplay -
dvrescue -v 7 tape001_pass1.dv --xml-output tape001_pass1.dvrescue.xml
dvrescue -v 7 tape001_pass2.dv --xml-output tape001_pass2.dvrescue.xml
dvrescue -v 9 tape001_pass1.dv tape001_pass2.dv --merge tape001_merged.dv --merge-log tape001_merge.log
dvrescue -v 7 tape001_merged.dv --xml-output tape001_merged.dvrescue.xml
dvplay -x tape001_merged.dv
dvpackager -e mkv -S tape001_merged.dv
```

--------------------------------

### Basic DV Stream Repackaging with DVPackager

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/packaging.md

Demonstrates the basic usage of dvpackager to rewrap DV frames into an output file. It automatically creates new output files when significant technical characteristics change or when frames with recording-start flags are encountered.

```bash
dvpackager -s INPUT.dv
```

--------------------------------

### Analyze DV Streams and Capture with dvrescue CLI

Source: https://context7.com/mipops/dvrescue/llms.txt

The `dvrescue` command-line tool analyzes DV streams, captures content from DV devices, and merges multiple transfers. It outputs detailed XML reports on metadata, errors, and recording characteristics. It supports various options for verbosity, closed caption extraction (SCC, SRT), device listing and status, playback control, and capturing to files.

```bash
# Basic analysis - outputs XML to console
dvrescue path/to/video.dv

# Save XML analysis to file
dvrescue path/to/video.dv --xml-output video.dvrescue.xml

# Analyze with verbosity (9 = per-frame info + summary)
dvrescue -v 9 path/to/video.dv

# Extract closed captions to SCC format
dvrescue path/to/video.dv --cc-format scc --cc-output captions.scc

# Extract closed captions to SRT format
dvrescue path/to/video.dv --cc-format srt --cc-output captions.srt

# List connected DV devices
dvrescue --list_devices

# List devices in JSON format
dvrescue --list_devices_json

# Check device status
dvrescue --status device://0

# Control playback on device
dvrescue --cmd play device://0
dvrescue --cmd stop device://0
dvrescue --cmd rew device://0
dvrescue --cmd ff device://0

# Capture from device to file
dvrescue device://0x800460104ce2bad -m /path/to/output.dv

# Capture with preview window
dvrescue device://0x800460104ce2bad -m /path/to/output.dv -m - | ffplay - 

# Capture with automatic rewind on errors (3 attempts)
dvrescue device://0x800460104ce2bad -y --rewind-count 3 -m output.dv -m - | ffplay - 

# Merge multiple transfers into one optimal file
dvrescue -v 9 file-pass-1.dv file-pass-2.dv file-pass-3.dv --merge merged-output.dv

# Merge with log file
dvrescue -v 9 file1.dv file2.dv --merge merged.dv --merge-log merge-log.txt

# Output analysis in CSV format
dvrescue --csv path/to/video.dv
```

--------------------------------

### Configure Audio Resampling in DVPackager

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/packaging.md

Provides options to control how audio sampling rates are handled during the packaging process. By default, it preserves the native rate, but can force resampling to 48000 Hz or create new files for each sampling rate change.

```bash
dvpackager -3  # Keep native sampling rate, may create more files
dvpackager -4  # Force all audio to be resampled to 48000 Hz
```

--------------------------------

### DVRescue CMake Configuration

Source: https://github.com/mipops/dvrescue/blob/main/Project/CMake/CMakeLists.txt

This snippet defines the main CMake configuration for the DVRescue project. It sets the minimum CMake version, finds required libraries (ZenLib, MediaInfoLib), defines source files, and configures the main executable target. It also handles platform-specific options for building the 'avfctl' tool on macOS.

```cmake
project(dvrescue)

cmake_minimum_required(VERSION 2.8.11)

find_package(ZenLib REQUIRED)
find_package(MediaInfoLib REQUIRED)

if(APPLE)
  option(BUILD_AVFCTL "Build avfctl tool (macOS only)" ON)
else()
  set(BUILD_AVFCTL OFF)
endif()

set(dvrescue_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../..)
set(dvrescue_SOURCES_PATH ${dvrescue_ROOT_PATH}/Source)

set(dvrescue_SRCS
  ${dvrescue_SOURCES_PATH}/CLI/CLI_Help.cpp
  ${dvrescue_SOURCES_PATH}/CLI/CLI_Main.cpp
  ${dvrescue_SOURCES_PATH}/CLI/CommandLine_Parser.cpp
  ${dvrescue_SOURCES_PATH}/CLI/DVRescue.rc
  ${dvrescue_SOURCES_PATH}/Common/Core.cpp
  ${dvrescue_SOURCES_PATH}/Common/Merge.cpp
  ${dvrescue_SOURCES_PATH}/Common/Output.cpp
  ${dvrescue_SOURCES_PATH}/Common/Output_Webvtt.cpp
  ${dvrescue_SOURCES_PATH}/Common/Output_Xml.cpp
  ${dvrescue_SOURCES_PATH}/Common/ProcessFile.cpp
  ${dvrescue_SOURCES_PATH}/Source/ThirdParty/ccdecoder/ccdecoder_internal.c
  ${dvrescue_SOURCES_PATH}/Source/ThirdParty/ccdecoder/ccdecoder_line21.c
  ${dvrescue_SOURCES_PATH}/Source/ThirdParty/ccdecoder/ccdecoder_line21field.c
  ${dvrescue_SOURCES_PATH}/Source/ThirdParty/ccdecoder/ccdecoder_onscreen.c
  ${dvrescue_SOURCES_PATH}/Source/ThirdParty/ccdecoder/ccdecoder_subrip.c
  ${dvrescue_SOURCES_PATH}/Source/ThirdParty/TimeCode/TimeCode.cpp
)

set(dvrescue_TOOLS
  ${dvrescue_ROOT_PATH}/tools/dvloupe
  ${dvrescue_ROOT_PATH}/tools/dvmap
  ${dvrescue_ROOT_PATH}/tools/dvpackager
  ${dvrescue_ROOT_PATH}/tools/dvplay
  ${dvrescue_ROOT_PATH}/tools/dvsampler
)

if(BUILD_AVFCTL)
  add_custom_command(OUTPUT ${dvrescue_ROOT_PATH}/tools/avfctl/avfctl
                     COMMAND make
                     WORKING_DIRECTORY ${dvrescue_ROOT_PATH}/tools/avfctl
  )
  add_custom_target(avfctl ALL DEPENDS ${dvrescue_ROOT_PATH}/tools/avfctl/avfctl)
  list(APPEND dvrescue_TOOLS ${dvrescue_ROOT_PATH}/tools/avfctl/avfctl)
endif()

add_executable(dvrescue
  ${dvrescue_SRCS}
)
target_include_directories(dvrescue
  PRIVATE ${dvrescue_SOURCES_PATH}
  PRIVATE ${dvrescue_SOURCES_PATH}/ThirdParty/ccdecoder
  PRIVATE ${dvrescue_SOURCES_PATH}/ThirdParty/TimeCode
)
target_link_libraries(dvrescue
  ${ZenLib_LIBRARY}
  ${MediaInfoLib_LIBRARY}
)

install(TARGETS dvrescue DESTINATION bin)
if(UNIX)
  install(PROGRAMS ${dvrescue_TOOLS} DESTINATION bin)
endif()

if(NOT TARGET uninstall)
  configure_file(
    "${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"
    "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"
    IMMEDIATE @ONLY
  )
  add_custom_target(uninstall
    "${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"
  )
endif()
```

--------------------------------

### Generate DV Test Files with dvsampler

Source: https://context7.com/mipops/dvrescue/llms.txt

dvsampler automates the download of sample DV files from sources like ffmpeg.org and generates additional test files with specific DV characteristics. These generated files are useful for testing DVRescue tools and workflows. The tool creates a 'samples/' directory containing various DV file formats.

```bash
# Run dvsampler to download samples and generate test files
./dvsampler

# Sample files are created in ./samples/ directory including:
# - dv25_ntsc_411_4-3_2ch_48k_bars_sine.dv
# - dv25_ntsc_411_169_2ch_48k_bars_sine.dv
# - dv25_pal__411_4-3_2ch_48k_bars_sine.dv
# - dv25_pal__411_4-3_2ch_32k_bars_sine.dv
# - dv25_pal__420_4-3_2ch_48k_bars_sine.dv
# - dv50_ntsc_422_4-3_2ch_48k_bars_sine.dv
# - dv50_pal__422_4-3_2ch_48k_bars_sine.dv
# - mix.dv (concatenation of all above)
```

--------------------------------

### Specify Custom Tool Paths for DVPackager

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/packaging.md

Allows users to specify custom paths for external tools like ffmpeg, mediainfo, dvrescue, and xmlstarlet. This is useful when these tools are not in the system's PATH or when using specific versions.

```bash
dvpackager -F /path/to/custom/ffmpeg
dvpackager -M /path/to/custom/mediainfo
dvpackager -D /path/to/custom/dvrescue
dvpackager -X /path/to/custom/xmlstarlet
```

--------------------------------

### Package DV Streams into Preservation Containers with dvpackager CLI

Source: https://context7.com/mipops/dvrescue/llms.txt

The `dvpackager` command-line tool rewraps raw DV streams into preservation containers like MOV or MKV. It uses `dvrescue` XML data to intelligently segment outputs based on changes in aspect ratio, frame rate, audio sample rate, recording markers, or timecode discontinuities. It also supports unpackaging DV streams from containers.

```bash
# Basic packaging to MOV (default)
dvpackager video.dv

# Package to Matroska container
dvpackager -e mkv video.dv

# Package to custom output directory
dvpackager -o /output/directory video.dv

# Split on recording start markers
dvpackager -s video.dv

# Split on non-consecutive recording timestamps
dvpackager -d video.dv

# Split on timecode jumps
dvpackager -t video.dv

# Combine multiple split options
dvpackager -s -d -t video.dv

# Preview segmentation without creating files
dvpackager -n video.dv

# Skip specific segments (skip segments 1 and 3)
dvpackager -N '1,3' video.dv

# Force all audio to 48kHz
dvpackager -4 video.dv

# Keep native audio sample rates (may create more output files)
dvpackager -3 video.dv

# Handle aspect ratio changes - force 4:3
dvpackager -a 4 video.dv

# Handle aspect ratio changes - force 16:9
dvpackager -a 9 video.dv

# Handle aspect ratio changes - use most common in segment
dvpackager -a c video.dv

# Custom output filename pattern
dvpackager -O "%FILENAME%_%RECDATE%_%TC%" video.dv

# Add language metadata to audio tracks
dvpackager -l "eng,spa" video.dv

# Embed captions track
dvpackager -S video.dv

# Generate DVRescue technical subtitles
dvpackager -Z video.dv

# Unpackage mode - extract DV from containers
dvpackager -u input1.mkv input2.mkv input3.mkv

# Show verbose ffmpeg output
dvpackager -v video.dv

# Display table of segments from XML
dvpackager -T video.dvrescue.xml video.dv
```

--------------------------------

### Generate Repackaging Table with DVPackager

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/packaging.md

Allows the generation of a table detailing how a file would be repackaged based on an XML input, without actually creating the output files. This is useful for previewing the repackaging process and its outcomes.

```bash
dvpackager -s -a c -T file.dv.dvrescue.xml file.dv
```

--------------------------------

### DVPackager Output Directory and Pattern

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/packaging.md

Specify custom output directories and define patterns for naming output files.

```APIDOC
## Output Directory and Pattern

### Description
Customize the output directory and define a pattern for naming output files.

### Options
- **-o <dir>** = Provide a custom output directory.
- **-O <pattern>** = Specify a pattern for output files. The following variables may be used:
  - `%FILENAME%` - will use the filename of the input file without its extension.
  - `%RECDATE%` - will use the recording date of the first output frame, in YYYY-MM-DD format. If there is no embedded recording date, then 'XXXX-XX-XX' will be used.
  - `%RECTIME%` - will use the recording date of the first output frame. If there is no embedded recording date, then 'XX-XX-XX' will be used.
  - `%TC%` - will use the timecode value of the first frame or use XX-XX-XX-XX if no timecode is stored in the first frame.
  - `%PARTNO%` - This is an incrementing number of the output starting from 1.

The default pattern is "%FILENAME%_part%PARTNO%". The extension of the output file is determined by the -e setting.

Note that if the output pattern would generate multiple output files with the same name then a 3-digit incrementing number such as "-001" will be added to the end of the filename.
```

--------------------------------

### Specify Custom DVRescue Metadata Files

Source: https://github.com/mipops/dvrescue/blob/main/docs/_sections/packaging.md

Enables the use of custom DVRescue-generated metadata files, including XML and technical subtitle (VBI) files. These files provide detailed information about the DV stream, aiding in accurate repackaging.

```bash
dvpackager -x /path/to/dvrescue.xml
dvpackager -V /path/to/dvrescue.vbi
dvpackager -C /path/to/dvrescue.scc
```