vssource


Namevssource JSON
Version 0.12.3 PyPI version JSON
download
home_pageNone
SummaryVapoursynth Wrapper for indexing and similar.
upload_time2025-02-13 14:30:46
maintainerSetsugen no ao
docs_urlNone
authorSetsugen no ao
requires_python>=3.12
licenseNone
keywords
VCS
bugtrack_url
requirements VapourSynth vstools
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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
    +----------+------+---+
```

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "vssource",
    "maintainer": "Setsugen no ao",
    "docs_url": null,
    "requires_python": ">=3.12",
    "maintainer_email": "setsugen@setsugen.dev",
    "keywords": null,
    "author": "Setsugen no ao",
    "author_email": "setsugen@setsugen.dev",
    "download_url": "https://files.pythonhosted.org/packages/fa/c7/cf87598c758fe67d9f9403e5a4d0699896fa3d6179543e01a7a84711027a/vssource-0.12.3.tar.gz",
    "platform": null,
    "description": "# vs-source\n\n> [!CAUTION]\n> This package is deprecated!\n> Please use https://github.com/Jaded-Encoding-Thaumaturgy/vs-jetpack instead.\n\n## DVDs were a mistake, but it doesn't have to feel _that_ bad to work with them\n\n<br>\n\nA wrapper for DVD file structure and ISO files.\n\nFor support you can check out the [JET Discord server](https://discord.gg/XTpc6Fa9eB). <br><br> <br><br>\n\n## How to install\n**This package is deprecated!**\n\nPlease install https://pypi.org/p/vsjetpack instead.\n\n<br>\nOne of the following plugins is required:\n\n- [dvdsrc2](https://github.com/jsaowji/dvdsrc2/)\n- d2vSource and either DGIndex or [patched d2vwitch](https://gist.github.com/jsaowji/ead18b4f1b90381d558eddaf0336164b)\n\n> _DGIndex is recommended over d2vwitch as the latter has various problems._\n>\n> DGIndex can also be used under linux with wine; notice that doing it requires ` binfmt` and `dgindex` in PATH.\n>\n> ```bash\n> chmod +x DGIndex.exe\n> sudo ln -s $(pwd)/DGIndex.exe /usr/bin/dgindex\n> ```\n\n<br>\n\nOptional dependecies:\n\n- [dvdsrc_dvdnav_title_ptt_test](https://gist.github.com/jsaowji/2bbf9c776a3226d1272e93bb245f7538) to automatically check the chapters against `libdvdnav`.\n- [dvdsrc](https://github.com/jsaowji/dvdsrc/) to automatically double-check the determined dvdstrucut agaist libdvdread.\n- [mpv](https://github.com/mpv-player/mpv) to determine chapter splits by loading the DVD and hitting I or using it like this:\n\n  > ```bash\n  > mpv --dvd-device=<iso> dvd://<title>\n  > # mpv titles are zero-indexed\n  > # vssource titles indices start from 1\n  > # sometimes it is useful to to scale the osc down\n  > # --script-opts=osc-scalewindowed=0.4,osc-scalefullscreen=0.4\n  > ```\n\n  Related to mpv, the [mpv-dvd-browser](https://github.com/CogentRedTester/mpv-dvd-browser) plugin may be useful for this too.\n\n<br>\n\nGetting a `vs.AudioNode` and demuxing AC3 **requires** [dvdsrc2](https://github.com/jsaowji/dvdsrc2/)\n\n**The only offically supported audio codecs are:**\n\n- stereo 16bit LPCM\n- AC3\n\n## Usage\n\n### Basic Usage\n\nPreviewing a title and dumping AC3 audio:\n\n```py\nfrom vssource import IsoFile, D2VWitch, DGIndex\nfrom vstools import set_output\n\n# Create an IsoFile object from a DVD ISO or folder path\n# This will automatically detect and use the best available indexer\niso = IsoFile('.\\DVD_VIDEOS\\Suzumiya_2009_DVD\\KABA_6001.ISO')\n\n# You can also explicitly specify which indexer to use\n# This example forces DGIndex even if other indexers are available\niso = IsoFile('.\\SOME_DVD_FOLDER\\HARUHI', indexer=DGIndex)\n\n# Get a Title object representing the first title on the DVD\n# Titles are 1-indexed\ntitle = iso.get_title(1)\n\n# Print information about the title\nprint(title)\n\n# Preview the video in your previewer\n# This outputs the entire video track of the title\ntitle.preview()\n\n# Preview the first audio track\ntitle.audios[0].preview()\n\n# Extract the AC3 audio from the first audio track (index 0)\n# This dumps the raw AC3 stream to a file\n# Note: Requires the dvdsrc2 plugin\ntitle.dump_ac3('full_title.ac3', 0)\n```\n\nSplitting titles:\n\n```py\n# Split a title into multiple parts at specific chapter boundaries\n# This splits at chapters 6 and 11, creating 3 parts:\n# - ep1: chapters 1-5\n# - ep2: chapters 6-10\n# - ep3: chapters 11-end\nep1, ep2, ep3 = title.split_at([6, 11])\n\n# Split a title into specific chapter ranges\n# Each tuple defines (start_chapter, end_chapter) inclusive\n# This creates 3 parts from chapters 1-5, 6-10, and 11-15\n# Any chapters after 15 are dropped\nep1, ep2, ep3 = title.split_ranges([(1, 5), (6, 10), (11, 15)])\n\n# Split individual ranges one at a time\n# Using -1 as end_chapter takes all remaining chapters\nep1 = title.split_range(1, 5)    # Chapters 1-5\nep2 = title.split_range(6, 10)   # Chapters 6-10\nep3 = title.split_range(11, -1)  # Chapter 11 to end\n\n# Preview the full title and its splits in your video previewer\n# This will output the full title and the individual parts after splitting at chapters 6 and 11\ntitle.preview(title.split_at([6, 11]))\n\n# Dump the first episode split's AC3 audio to a file and get the audio offset.\n# The returned value is the offset in seconds between the start of the audio\n# and the start of the video. This is useful for syncing audio and video,\n# since DVD AC3 audio frames don't perfectly align with chapter boundaries.\n# A positive value means there is extra audio at the start that needs trimming.\nep1_ac3_offset = ep1.ac3('ep1.ac3', 0)\n```\n\n### Advanced Usage\n\nTrimming unwanted frames from a title\n\n```py\n# Sometimes DVDs have junk frames at the end of titles that we want to remove\ntitle1 = iso.get_title(1)\n# Remove 609 frames from the last chapter\ntitle1.chapters[-1] -= 609\n# Split into episodes at chapters 7 and 12, and preview the splits\ntitle1.preview(title1.split_at([7, 12]))\n```\n\nBatch processing multiple titles\n\n```py\n# Here we process titles 2-5 which contain episodes\n# Each title has some junk frames at the start we want to trim\nsplits = []\n\nfor title_num in range(2, 6):\n    title = iso.get_title(title_num)\n    # Add 180 frames offset to first chapter to skip junk frames\n    title.chapters[0] += 180\n    # Split and store the processed title\n    splits.append(title.split_at([]))\n    # Preview to verify the trim looks correct\n    title.preview(splits[-1])\n\n# Extract audio from first split and get sync offset\naudio_offset = splits[0].ac3('ep1.ac3')\nprint(f\"Audio offset: {audio_offset:.3f} seconds\")\n```\n\nWorking with multi-angle content and different audio tracks\n\n```py\n# Get title 4 with angle 1 (Japanese video) and audio track 1\n# rff_mode=2 enables repeat-field flags for proper frame timing\njapanese = iso.get_title(4, angle_nr=1, rff_mode=2).split_at([5, 10, 15], audio=1)\n\n# Preview episode 1 Japanese video and audio\njapanese[0].preview()\n\n# Get same title with angle 2 (Italian video) and audio track 0\nitalian = iso.get_title(4, angle_nr=2, rff_mode=2).split_at([5, 10, 15], audio=0)\n\n# Preview episode 2 Italian video and audio\nitalian[1].preview()\n```\n\nThe `Title` class provides two main methods for splitting DVD titles into segments:\n\n`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:\n\n- `split_at([5])` splits the title into two parts:\n  1. Chapters 1-4\n  2. Chapters 5-end\n\n`split_range(start, end)`: Extracts a range of chapters inclusively. For example:\n\n- `split_range(2, 4)` extracts chapters 2-4\n\nThe output chapters are 1-based and match the DVD chapter numbers. This matches how DVD chapters work, where:\n\n- Chapter 1 is the first chapter\n- Splits occur at chapter boundaries\n- Chapter numbers match what you see in DVD menus and players\n\n```py\n+---+----------+------+---+---+--------+--------+---+\n| 1 |     2    |   3  | 4 | 5 |    6   |    7   | 8 |\n+---+----------+------+---+---+--------+--------+---+\n\nsplit_at([5])\n+---+----------+------+---+\n| 1 |     2    |   3  | 4 |  # First segment: Chapters 1-4\n+---+----------+------+---+\n                           +---+--------+--------+---+\n                           | 5 |    6   |    7   | 8 |  # Second segment: Chapters 5-8\n                           +---+--------+--------+---+\n\nsplit_at([3, 6])\n+---+----------+\n| 1 |     2    |  # First segment: Chapters 1-2\n+---+----------+\n               +------+---+---+\n               |   3  | 4 | 5 |  # Second segment: Chapters 3-5\n               +------+---+---+\n                              +--------+--------+---+\n                              |    6   |    7   | 8 |  # Third segment: Chapters 6-8\n                              +--------+--------+---+\n\nsplit_range(2, 4)\n    +----------+------+---+\n    |     2    |   3  | 4 |  # Extracts just chapters 2-4\n    +----------+------+---+\n```\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Vapoursynth Wrapper for indexing and similar.",
    "version": "0.12.3",
    "project_urls": {
        "Contact": "https://discord.gg/XTpc6Fa9eB",
        "Source Code": "https://github.com/Jaded-Encoding-Thaumaturgy/vs-source"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "ef0638bc68e72b4151156e4b7a03bea67399feb83300aaec63618d88667c5ecf",
                "md5": "3bfa02a0a016eea62e9d838f0589481d",
                "sha256": "f60d5c13645fa7b9ffd530d7e818bd005a65cc2e00ea14ad589a605fedb0bd87"
            },
            "downloads": -1,
            "filename": "vssource-0.12.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "3bfa02a0a016eea62e9d838f0589481d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 39554,
            "upload_time": "2025-02-13T14:30:45",
            "upload_time_iso_8601": "2025-02-13T14:30:45.129232Z",
            "url": "https://files.pythonhosted.org/packages/ef/06/38bc68e72b4151156e4b7a03bea67399feb83300aaec63618d88667c5ecf/vssource-0.12.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "fac7cf87598c758fe67d9f9403e5a4d0699896fa3d6179543e01a7a84711027a",
                "md5": "d9dd764922fb1a129ded1a82bfa0ce17",
                "sha256": "8a830a51fab2aebe4f49966c88bd53ab02f0cc8e422be1cd60aec23cc62e08fb"
            },
            "downloads": -1,
            "filename": "vssource-0.12.3.tar.gz",
            "has_sig": false,
            "md5_digest": "d9dd764922fb1a129ded1a82bfa0ce17",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 34734,
            "upload_time": "2025-02-13T14:30:46",
            "upload_time_iso_8601": "2025-02-13T14:30:46.292651Z",
            "url": "https://files.pythonhosted.org/packages/fa/c7/cf87598c758fe67d9f9403e5a4d0699896fa3d6179543e01a7a84711027a/vssource-0.12.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-13 14:30:46",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Jaded-Encoding-Thaumaturgy",
    "github_project": "vs-source",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "VapourSynth",
            "specs": [
                [
                    ">=",
                    "68"
                ]
            ]
        },
        {
            "name": "vstools",
            "specs": [
                [
                    ">=",
                    "3.4.1"
                ]
            ]
        }
    ],
    "lcname": "vssource"
}
        
Elapsed time: 0.39015s