vssource 0.12.4
Vapoursynth Wrapper for indexing and similar.
Requires Python: >=3.12

# vs-source

> [!CAUTION]
> This package is deprecated!
> Please use https://github.com/Jaded-Encoding-Thaumaturgy/vs-jetpack instead.

## DVDs were a mistake, but it doesn't have to feel _that_ bad to work with them

<br>

A wrapper for DVD file structure and ISO files.

For support you can check out the [JET Discord server](https://discord.gg/XTpc6Fa9eB). <br><br> <br><br>

## How to install
**This package is deprecated!**

Please install https://pypi.org/p/vsjetpack instead.

<br>
One of the following plugins is required:

- [dvdsrc2](https://github.com/jsaowji/dvdsrc2/)
- d2vSource and either DGIndex or [patched d2vwitch](https://gist.github.com/jsaowji/ead18b4f1b90381d558eddaf0336164b)

> _DGIndex is recommended over d2vwitch as the latter has various problems._
>
> DGIndex can also be used under linux with wine; notice that doing it requires ` binfmt` and `dgindex` in PATH.
>
> ```bash
> chmod +x DGIndex.exe
> sudo ln -s $(pwd)/DGIndex.exe /usr/bin/dgindex
> ```

<br>

Optional dependecies:

- [dvdsrc_dvdnav_title_ptt_test](https://gist.github.com/jsaowji/2bbf9c776a3226d1272e93bb245f7538) to automatically check the chapters against `libdvdnav`.
- [dvdsrc](https://github.com/jsaowji/dvdsrc/) to automatically double-check the determined dvdstrucut agaist libdvdread.
- [mpv](https://github.com/mpv-player/mpv) to determine chapter splits by loading the DVD and hitting I or using it like this:

  > ```bash
  > mpv --dvd-device=<iso> dvd://<title>
  > # mpv titles are zero-indexed
  > # vssource titles indices start from 1
  > # sometimes it is useful to to scale the osc down
  > # --script-opts=osc-scalewindowed=0.4,osc-scalefullscreen=0.4
  > ```

  Related to mpv, the [mpv-dvd-browser](https://github.com/CogentRedTester/mpv-dvd-browser) plugin may be useful for this too.

<br>

Getting a `vs.AudioNode` and demuxing AC3 **requires** [dvdsrc2](https://github.com/jsaowji/dvdsrc2/)

**The only offically supported audio codecs are:**

- stereo 16bit LPCM
- AC3

## Usage

### Basic Usage

Previewing a title and dumping AC3 audio:

```py
from vssource import IsoFile, D2VWitch, DGIndex
from vstools import set_output

# Create an IsoFile object from a DVD ISO or folder path
# This will automatically detect and use the best available indexer
iso = IsoFile('.\DVD_VIDEOS\Suzumiya_2009_DVD\KABA_6001.ISO')

# You can also explicitly specify which indexer to use
# This example forces DGIndex even if other indexers are available
iso = IsoFile('.\SOME_DVD_FOLDER\HARUHI', indexer=DGIndex)

# Get a Title object representing the first title on the DVD
# Titles are 1-indexed
title = iso.get_title(1)

# Print information about the title
print(title)

# Preview the video in your previewer
# This outputs the entire video track of the title
title.preview()

# Preview the first audio track
title.audios[0].preview()

# Extract the AC3 audio from the first audio track (index 0)
# This dumps the raw AC3 stream to a file
# Note: Requires the dvdsrc2 plugin
title.dump_ac3('full_title.ac3', 0)
```

Splitting titles:

```py
# Split a title into multiple parts at specific chapter boundaries
# This splits at chapters 6 and 11, creating 3 parts:
# - ep1: chapters 1-5
# - ep2: chapters 6-10
# - ep3: chapters 11-end
ep1, ep2, ep3 = title.split_at([6, 11])

# Split a title into specific chapter ranges
# Each tuple defines (start_chapter, end_chapter) inclusive
# This creates 3 parts from chapters 1-5, 6-10, and 11-15
# Any chapters after 15 are dropped
ep1, ep2, ep3 = title.split_ranges([(1, 5), (6, 10), (11, 15)])

# Split individual ranges one at a time
# Using -1 as end_chapter takes all remaining chapters
ep1 = title.split_range(1, 5)    # Chapters 1-5
ep2 = title.split_range(6, 10)   # Chapters 6-10
ep3 = title.split_range(11, -1)  # Chapter 11 to end

# Preview the full title and its splits in your video previewer
# This will output the full title and the individual parts after splitting at chapters 6 and 11
title.preview(title.split_at([6, 11]))

# Dump the first episode split's AC3 audio to a file and get the audio offset.
# The returned value is the offset in seconds between the start of the audio
# and the start of the video. This is useful for syncing audio and video,
# since DVD AC3 audio frames don't perfectly align with chapter boundaries.
# A positive value means there is extra audio at the start that needs trimming.
ep1_ac3_offset = ep1.ac3('ep1.ac3', 0)
```

### Advanced Usage

Trimming unwanted frames from a title

```py
# Sometimes DVDs have junk frames at the end of titles that we want to remove
title1 = iso.get_title(1)
# Remove 609 frames from the last chapter
title1.chapters[-1] -= 609
# Split into episodes at chapters 7 and 12, and preview the splits
title1.preview(title1.split_at([7, 12]))
```

Batch processing multiple titles

```py
# Here we process titles 2-5 which contain episodes
# Each title has some junk frames at the start we want to trim
splits = []

for title_num in range(2, 6):
    title = iso.get_title(title_num)
    # Add 180 frames offset to first chapter to skip junk frames
    title.chapters[0] += 180
    # Split and store the processed title
    splits.append(title.split_at([]))
    # Preview to verify the trim looks correct
    title.preview(splits[-1])

# Extract audio from first split and get sync offset
audio_offset = splits[0].ac3('ep1.ac3')
print(f"Audio offset: {audio_offset:.3f} seconds")
```

Working with multi-angle content and different audio tracks

```py
# Get title 4 with angle 1 (Japanese video) and audio track 1
# rff_mode=2 enables repeat-field flags for proper frame timing
japanese = iso.get_title(4, angle_nr=1, rff_mode=2).split_at([5, 10, 15], audio=1)

# Preview episode 1 Japanese video and audio
japanese[0].preview()

# Get same title with angle 2 (Italian video) and audio track 0
italian = iso.get_title(4, angle_nr=2, rff_mode=2).split_at([5, 10, 15], audio=0)

# Preview episode 2 Italian video and audio
italian[1].preview()
```

The `Title` class provides two main methods for splitting DVD titles into segments:

`split_at([chapters])`: Splits a title at the specified chapter numbers, similar to how mkvmerge handles chapter splits. The splits occur before each specified chapter. For example:

- `split_at([5])` splits the title into two parts:
  1. Chapters 1-4
  2. Chapters 5-end

`split_range(start, end)`: Extracts a range of chapters inclusively. For example:

- `split_range(2, 4)` extracts chapters 2-4

The output chapters are 1-based and match the DVD chapter numbers. This matches how DVD chapters work, where:

- Chapter 1 is the first chapter
- Splits occur at chapter boundaries
- Chapter numbers match what you see in DVD menus and players

```py
+---+----------+------+---+---+--------+--------+---+
| 1 |     2    |   3  | 4 | 5 |    6   |    7   | 8 |
+---+----------+------+---+---+--------+--------+---+

split_at([5])
+---+----------+------+---+
| 1 |     2    |   3  | 4 |  # First segment: Chapters 1-4
+---+----------+------+---+
                           +---+--------+--------+---+
                           | 5 |    6   |    7   | 8 |  # Second segment: Chapters 5-8
                           +---+--------+--------+---+

split_at([3, 6])
+---+----------+
| 1 |     2    |  # First segment: Chapters 1-2
+---+----------+
               +------+---+---+
               |   3  | 4 | 5 |  # Second segment: Chapters 3-5
               +------+---+---+
                              +--------+--------+---+
                              |    6   |    7   | 8 |  # Third segment: Chapters 6-8
                              +--------+--------+---+

split_range(2, 4)
    +----------+------+---+
    |     2    |   3  | 4 |  # Extracts just chapters 2-4
    +----------+------+---+
```