| Name | vssource JSON |
| Version |
0.12.3
JSON |
| download |
| home_page | None |
| Summary | Vapoursynth Wrapper for indexing and similar. |
| upload_time | 2025-02-13 14:30:46 |
| maintainer | Setsugen no ao |
| docs_url | None |
| author | Setsugen no ao |
| requires_python | >=3.12 |
| license | None |
| 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"
}
