| Name | vmt JSON |
| Version |
0.0.0b10
JSON |
| download |
| home_page | |
| Summary | Video Media Tracker. Local, and simple method for watching and tracking a video media library. |
| upload_time | 2023-06-21 07:42:21 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | GNU General Public License v3 (GPLv3) |
| keywords |
mpv
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# vmt
Track, play, and browse your locally accessible media.
<!-- ## Video demonstration & tl;dr -->
<!-- Don't like to read? Checkout -->
<!-- [this](https://vid.puffyan.us/watch?v=NeF56_JBagM) video where I go over -->
<!-- installation, configuration, and use of vmt. -->
## Why use vmt?
Good question.
You've got plenty of ways to watch and track your media. Popular options are
jellyfin or plex. These are great both applications, but for me they are totally
overkill.
My needs:
- [X] 100% offline functionality
- [X] 100% local tracking
- [X] Simple directory structure
- [X] Tracks last watched episodes
- [X] Tracks last watched shows
- [X] Full mpv support
I made vmt to tick all of these boxes and it does just that in a simple way.
## Only for local files?
Not necessarily. You can mount a remote filesystem using NFS, sshfs, or SMB.
I'm sure there are tons of other ways to mount remote file systems so that they
are available on your local machine.
The only requirement is that you can cd into the directory that has the files
you want to add to your library. If you can do that you can use vmt to track and
watch these videos.
## 100% local? 100% offline?
Yep. But it doesn't have to be.
Feel free to setup `~/.config/vmt` as a syncthing share and keep your library
and progress synced across your laptop(s) and desktop(s), maybe even your phone
via termux (untested but maybe).
## Installation
Can install the usual way:
```bash
pip install vmt
```
Then run `vmt --build` and get taken through the setup process via a TUI interface.
### Dependencies
- dmenu, fzf, or rofi
- mpv
## Using vmt
Now that you've built your library you can start watching and tracking your anime.
As you've just built your library you don't have a log yet. Because of that you
are going to want to run this command, either through dmenu, a terminal, or via
some hot-key:
```bash
vmt -w
```
You will get prompted with a list of all the titles in your library. Select one
of the show titles and you will get another prompt displaying all the episodes
found for that show. Select an episode and watch some anime.
Please see [this](https://github.com/johndovern/vmt#Note-on-use-with-hot-keys)
section for more info on starting vmt via a hot-key or dmenu.
### Watching your last watched shows
At this point vmt is tracking the shows you watch in your library and history log. You can now run following command through dmenu, a terminal, or via a hot-key:
```bash
vmt -l
```
With this you will see a dmenu or fzf prompt showing you the titles of your last
watched shows. These shows are getting tracked which means once you select one mpv
will open and start playing your last watched episode.
It is advisable that you close mpv on the episode you wish to resume. You can
also use `Q` instead of `q` to save and quit (an mpv native feature which has
nothing to do with vmt). Then you'll start off exactly where you left off.
## vmt.lua
The secret sauce of vmt is the vmt.lua script. This script can work in two ways:
1. Enable it by default via `script-opts/vmt.conf` by setting
`enabled=yes`
2. Enable it when you run mpv like so
`mpv --script-opts=vmt-enabled=yes /path/to/file`
The full path to `script-opts/vmt.conf` is `~/.config/mpv/script-opts/vmt.conf`.
If you leave this file alone you must launch mpv with
`mpv --script-opts=vmt-enabled=yes /path/to/file` to enable vmt.lua.
This is too long to type out. Instead you can use vmt as an mpv wrapper by
running `vmt -o /path/to/file` which will enable vmt.lua. Both `vmt -w` and `-l`
launch mpv in this way.
### How vmt.lua works
When enabled vmt.lua will get the currently playing file's path and set it to
the variable `trackPath`. After that it will run `vmt -s "$trackPath"`. The `-s,
--search` flag takes a file path and searches the shows in your library for the
given file. If the file gets found it will exit successfully. If it isn't found
vmt will exit with an error code.
If the search was successful vmt.lua will then run `vmt -t "$trackPath"`. The
`-t, --track` flag takes a file path. It repeats the same search as `-s` just to
be safe. If the search is successful your library and history log will be
updated appropriately.
## Updating your library
To update your library just run `vmt -u`. This will backup your current library
in case you don't like how the update went. You can use the `-c, --clean` flag
if you don't want to keep a backup.
When you update your library vmt will do it's best to detect any shows that
already exist in your library and still exist in your `base_dir`. If a show has
not changed locations then any episode progress will get carried over to the
updated library along with any title you may have set for the show.
If the shows directory has changed it will get treated as a new show and your
show progress will get lost. I do not have any simple way around this and I do
not consider this an issue.
Any new shows will get added with an automatically generated title.
### Updating interactively
If you wish to set the title yourself use the `-i, --interactive` flag. You should also use the `-d` flag and be sure to run vmt in a terminal.
Running `vmt -d -i -u` will give you a prompt asking you to set a title for the given show. It will also display either the previous title or an automatically generated title if the show is new. If you are using dmenu you can press ESC to accept the previous or automatic title. If you are using fzf this will be a read prompt in which case enter nothing to accept the previous or automatic title.
## Wrapping up
### Valid extensions
I mentioned earlier that only directories with valid file extensions are considered shows and added to your library. So what is a valid file extension? Well, here is a list of all file extensions that vmt considers valid:
- mkv
- mp4
- mpg
- mp2
- mpeg
- mpe
- mpv
- ogg
- webm
- m4p
- m4v
- avi
- wmv
- mov
- qt
- flv
- swf
- avchd
You might be thinking "Wow, that's a lot of extensions! The find command must be very long." Well, you're half right. That is a lot of extensions but the _find_ command is very short.
#### How vmt build's your library
This is the command that vmt uses to build your library:
```bash
while read -r DIR ; do
...
done < <(find "${BASE_DIR}" -type f -printf '%P\n' | \
sed '/^.*\.\(mkv\|mp4\|mpg\|mp2\|mpeg\|mpe\|mpv\|ogg\|webm\|m4p\|m4v\|avi\|wmv\|mov\|qt\|flv\|swf\|avchd\)$/!d;s/\(^.*\)\/.*$/\1/g' | \
sort -u)
```
Maybe it's just my system but when I give `find` a lot of flags it runs very slowly. For that reason I am using sed to filter find's results.
If a file path does not end in one of the given file extensions it is filtered from the results.
Any path that does end in a valid extension is then striped of the file leaving only the directory.
Finally we sort the directory results to ensure they are in alphabetical order and unique.
Pretty simple and most importantly fast. However, you want to make sure your `BASE_DIR` is as close to your videos as possible. Don't set it to `$HOME` if all your videos are in `~/Videos/Anime`.
### Automatically generated titles
I've mentioned these automatically generated titles a few times, but what the heck does that look like? Well, here is an example:
```bash
$ DIR="[Commie] Space Dandy - Volume 6 [BD 720p AAC]"
$ CLEAN_TITLE="$(printf '%s\n' "${DIR//\// - }" | sed 's/\s\+\?\[[^]]*\]\s\+\?//g')"
$ printf '%s\n' "${CLEAN_TITLE//[\!\\@#$%^&*\{\}\/<>?\'\":+\`|=]/-}"
Space Dandy - Volume 6
```
All the info that comes with a torrent is great but it doesn't look great. This it a pretty effective way of cleaning most directories and getting something that looks like a title.
Here is another example. This is a larger torrent with a path that is two directories deep:
```bash
$ DIR="[Anime Time] Little Busters! (S1+S2+S3+OVA) [BD][HEVC 10bit x265][AAC][Eng Sub]/Little Busters! Season 1"
$ CLEAN_TITLE="$(printf '%s\n' "${DIR//\// - }" | sed 's/\s\+\?\[[^]]*\]\s\+\?//g')"
$ printf '%s\n' "${CLEAN_TITLE//[\!\\@#$%^&*\{\}\/<>?\'\":+\`|=]/-}"
Little Busters- (S1-S2-S3-OVA) - Little Busters- Season 1
```
The output isn't perfect, but boy does it happen fast and looks a whole lot better.
When using vmt if you use the `-i` flag when updating or building your library you will get a chance to see a preview of what the title will look like if you enter nothing. So you can make the call on what you want your anime titles to be.
### Note on use with hot-keys
I use sxhkd to start vmt for most operations. I also use dmenu as my default prompt. If this is you then vmt will "just work".
If you use fzf you want to start vmt with a hot-key you will need to make sure you do this within a terminal. I use st which means I would put this in my sxhkdrc:
```bash
super + a
st -e vmt -w
```
This ensures that vmt is running in a terminal and that you will be able to respond to the fzf or read prompts.
### Browsing your BASE_DIR
If you've set a `FILE_MANAGER` then you can run vmt with the `-B, --browse` flag. This will open your `BASE_DIR` in your chosen FILE_MANAGER.
## Disclaimer
This project is considered complete. The scope of features I set out to implement has been achieved. If you have a feature suggestion I will gladly hear and consider it. I may add new features but at present I can't think of anything I would add to this project. If anything I would like to strip it down more and make it more portable.
I have done a limited amount of testing relative to the possible directory names and structures that vmt may encounter. If you run into an error (my guess is that it has to do with sed) then please open an issue with as much relevant information as needed. I will do my best to come up with a solution or review any proposed solutions.
Raw data
{
"_id": null,
"home_page": "",
"name": "vmt",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "mpv",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/ed/06/c244dfd4c3c5ea63e0b7f17172bf9813da2edb5227cc1a8b4df65d99a903/vmt-0.0.0b10.tar.gz",
"platform": null,
"description": "# vmt\nTrack, play, and browse your locally accessible media.\n\n<!-- ## Video demonstration & tl;dr -->\n<!-- Don't like to read? Checkout -->\n<!-- [this](https://vid.puffyan.us/watch?v=NeF56_JBagM) video where I go over -->\n<!-- installation, configuration, and use of vmt. -->\n\n## Why use vmt?\nGood question.\n\nYou've got plenty of ways to watch and track your media. Popular options are\njellyfin or plex. These are great both applications, but for me they are totally\noverkill.\n\nMy needs:\n\n - [X] 100% offline functionality\n - [X] 100% local tracking\n - [X] Simple directory structure\n - [X] Tracks last watched episodes\n - [X] Tracks last watched shows\n - [X] Full mpv support\n\nI made vmt to tick all of these boxes and it does just that in a simple way.\n\n## Only for local files?\nNot necessarily. You can mount a remote filesystem using NFS, sshfs, or SMB.\nI'm sure there are tons of other ways to mount remote file systems so that they\nare available on your local machine.\n\nThe only requirement is that you can cd into the directory that has the files\nyou want to add to your library. If you can do that you can use vmt to track and\nwatch these videos.\n\n## 100% local? 100% offline?\nYep. But it doesn't have to be.\n\nFeel free to setup `~/.config/vmt` as a syncthing share and keep your library\nand progress synced across your laptop(s) and desktop(s), maybe even your phone\nvia termux (untested but maybe).\n\n## Installation\nCan install the usual way:\n\n```bash\npip install vmt\n```\n\nThen run `vmt --build` and get taken through the setup process via a TUI interface.\n\n### Dependencies\n- dmenu, fzf, or rofi\n- mpv\n\n## Using vmt\nNow that you've built your library you can start watching and tracking your anime.\n\nAs you've just built your library you don't have a log yet. Because of that you\nare going to want to run this command, either through dmenu, a terminal, or via\nsome hot-key:\n\n```bash\nvmt -w\n```\n\nYou will get prompted with a list of all the titles in your library. Select one\nof the show titles and you will get another prompt displaying all the episodes\nfound for that show. Select an episode and watch some anime.\n\nPlease see [this](https://github.com/johndovern/vmt#Note-on-use-with-hot-keys)\nsection for more info on starting vmt via a hot-key or dmenu.\n\n### Watching your last watched shows\nAt this point vmt is tracking the shows you watch in your library and history log. You can now run following command through dmenu, a terminal, or via a hot-key:\n\n```bash\nvmt -l\n```\n\nWith this you will see a dmenu or fzf prompt showing you the titles of your last\nwatched shows. These shows are getting tracked which means once you select one mpv\nwill open and start playing your last watched episode.\n\nIt is advisable that you close mpv on the episode you wish to resume. You can\nalso use `Q` instead of `q` to save and quit (an mpv native feature which has\nnothing to do with vmt). Then you'll start off exactly where you left off.\n\n## vmt.lua\nThe secret sauce of vmt is the vmt.lua script. This script can work in two ways:\n\n 1. Enable it by default via `script-opts/vmt.conf` by setting\n\n `enabled=yes`\n\n 2. Enable it when you run mpv like so\n\n `mpv --script-opts=vmt-enabled=yes /path/to/file`\n\nThe full path to `script-opts/vmt.conf` is `~/.config/mpv/script-opts/vmt.conf`.\n\nIf you leave this file alone you must launch mpv with \n`mpv --script-opts=vmt-enabled=yes /path/to/file` to enable vmt.lua.\n\nThis is too long to type out. Instead you can use vmt as an mpv wrapper by\nrunning `vmt -o /path/to/file` which will enable vmt.lua. Both `vmt -w` and `-l`\nlaunch mpv in this way.\n\n### How vmt.lua works\nWhen enabled vmt.lua will get the currently playing file's path and set it to\nthe variable `trackPath`. After that it will run `vmt -s \"$trackPath\"`. The `-s,\n--search` flag takes a file path and searches the shows in your library for the\ngiven file. If the file gets found it will exit successfully. If it isn't found\nvmt will exit with an error code.\n\nIf the search was successful vmt.lua will then run `vmt -t \"$trackPath\"`. The\n`-t, --track` flag takes a file path. It repeats the same search as `-s` just to\nbe safe. If the search is successful your library and history log will be\nupdated appropriately.\n\n## Updating your library\nTo update your library just run `vmt -u`. This will backup your current library\nin case you don't like how the update went. You can use the `-c, --clean` flag\nif you don't want to keep a backup.\n\nWhen you update your library vmt will do it's best to detect any shows that\nalready exist in your library and still exist in your `base_dir`. If a show has\nnot changed locations then any episode progress will get carried over to the\nupdated library along with any title you may have set for the show.\n\nIf the shows directory has changed it will get treated as a new show and your\nshow progress will get lost. I do not have any simple way around this and I do\nnot consider this an issue.\n\nAny new shows will get added with an automatically generated title.\n\n### Updating interactively\nIf you wish to set the title yourself use the `-i, --interactive` flag. You should also use the `-d` flag and be sure to run vmt in a terminal.\n\nRunning `vmt -d -i -u` will give you a prompt asking you to set a title for the given show. It will also display either the previous title or an automatically generated title if the show is new. If you are using dmenu you can press ESC to accept the previous or automatic title. If you are using fzf this will be a read prompt in which case enter nothing to accept the previous or automatic title.\n\n## Wrapping up\n### Valid extensions\nI mentioned earlier that only directories with valid file extensions are considered shows and added to your library. So what is a valid file extension? Well, here is a list of all file extensions that vmt considers valid:\n\n - mkv\n - mp4\n - mpg\n - mp2\n - mpeg\n - mpe\n - mpv\n - ogg\n - webm\n - m4p\n - m4v\n - avi\n - wmv\n - mov\n - qt\n - flv\n - swf\n - avchd\n\nYou might be thinking \"Wow, that's a lot of extensions! The find command must be very long.\" Well, you're half right. That is a lot of extensions but the _find_ command is very short.\n\n#### How vmt build's your library\nThis is the command that vmt uses to build your library:\n\n```bash\n while read -r DIR ; do\n ...\n done < <(find \"${BASE_DIR}\" -type f -printf '%P\\n' | \\\n sed '/^.*\\.\\(mkv\\|mp4\\|mpg\\|mp2\\|mpeg\\|mpe\\|mpv\\|ogg\\|webm\\|m4p\\|m4v\\|avi\\|wmv\\|mov\\|qt\\|flv\\|swf\\|avchd\\)$/!d;s/\\(^.*\\)\\/.*$/\\1/g' | \\\n sort -u)\n```\n\nMaybe it's just my system but when I give `find` a lot of flags it runs very slowly. For that reason I am using sed to filter find's results.\n\nIf a file path does not end in one of the given file extensions it is filtered from the results.\n\nAny path that does end in a valid extension is then striped of the file leaving only the directory.\n\nFinally we sort the directory results to ensure they are in alphabetical order and unique.\n\nPretty simple and most importantly fast. However, you want to make sure your `BASE_DIR` is as close to your videos as possible. Don't set it to `$HOME` if all your videos are in `~/Videos/Anime`.\n\n### Automatically generated titles\nI've mentioned these automatically generated titles a few times, but what the heck does that look like? Well, here is an example:\n\n```bash\n$ DIR=\"[Commie] Space Dandy - Volume 6 [BD 720p AAC]\"\n$ CLEAN_TITLE=\"$(printf '%s\\n' \"${DIR//\\// - }\" | sed 's/\\s\\+\\?\\[[^]]*\\]\\s\\+\\?//g')\"\n$ printf '%s\\n' \"${CLEAN_TITLE//[\\!\\\\@#$%^&*\\{\\}\\/<>?\\'\\\":+\\`|=]/-}\"\nSpace Dandy - Volume 6\n```\n\nAll the info that comes with a torrent is great but it doesn't look great. This it a pretty effective way of cleaning most directories and getting something that looks like a title.\n\nHere is another example. This is a larger torrent with a path that is two directories deep:\n\n```bash\n$ DIR=\"[Anime Time] Little Busters! (S1+S2+S3+OVA) [BD][HEVC 10bit x265][AAC][Eng Sub]/Little Busters! Season 1\"\n$ CLEAN_TITLE=\"$(printf '%s\\n' \"${DIR//\\// - }\" | sed 's/\\s\\+\\?\\[[^]]*\\]\\s\\+\\?//g')\"\n$ printf '%s\\n' \"${CLEAN_TITLE//[\\!\\\\@#$%^&*\\{\\}\\/<>?\\'\\\":+\\`|=]/-}\"\nLittle Busters- (S1-S2-S3-OVA) - Little Busters- Season 1\n```\n\nThe output isn't perfect, but boy does it happen fast and looks a whole lot better.\n\nWhen using vmt if you use the `-i` flag when updating or building your library you will get a chance to see a preview of what the title will look like if you enter nothing. So you can make the call on what you want your anime titles to be.\n\n### Note on use with hot-keys\nI use sxhkd to start vmt for most operations. I also use dmenu as my default prompt. If this is you then vmt will \"just work\".\n\nIf you use fzf you want to start vmt with a hot-key you will need to make sure you do this within a terminal. I use st which means I would put this in my sxhkdrc:\n\n```bash\nsuper + a\n st -e vmt -w\n```\n\nThis ensures that vmt is running in a terminal and that you will be able to respond to the fzf or read prompts.\n\n### Browsing your BASE_DIR\nIf you've set a `FILE_MANAGER` then you can run vmt with the `-B, --browse` flag. This will open your `BASE_DIR` in your chosen FILE_MANAGER.\n\n## Disclaimer\nThis project is considered complete. The scope of features I set out to implement has been achieved. If you have a feature suggestion I will gladly hear and consider it. I may add new features but at present I can't think of anything I would add to this project. If anything I would like to strip it down more and make it more portable.\n\nI have done a limited amount of testing relative to the possible directory names and structures that vmt may encounter. If you run into an error (my guess is that it has to do with sed) then please open an issue with as much relevant information as needed. I will do my best to come up with a solution or review any proposed solutions.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "Video Media Tracker. Local, and simple method for watching and tracking a video media library.",
"version": "0.0.0b10",
"project_urls": {
"repository": "https://codeberg.org/johndovern/vmt"
},
"split_keywords": [
"mpv"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fa92a77558313a174c5751663dde537b52489bda71a8aa8e77efc95d928fdbc0",
"md5": "77e1574a9d71d229aa42b8c684691b67",
"sha256": "1e62808bab231f31a3f3400222fd10f97a5f3e13f739fafcf629cb4f7f2e956b"
},
"downloads": -1,
"filename": "vmt-0.0.0b10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "77e1574a9d71d229aa42b8c684691b67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 28912,
"upload_time": "2023-06-21T07:42:19",
"upload_time_iso_8601": "2023-06-21T07:42:19.781002Z",
"url": "https://files.pythonhosted.org/packages/fa/92/a77558313a174c5751663dde537b52489bda71a8aa8e77efc95d928fdbc0/vmt-0.0.0b10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ed06c244dfd4c3c5ea63e0b7f17172bf9813da2edb5227cc1a8b4df65d99a903",
"md5": "1e166e68790a5d01535ebad0f5a24009",
"sha256": "ce698951a61e799fa18ddf7e3445a177840bf0b4145a51e4c95d5e303161f098"
},
"downloads": -1,
"filename": "vmt-0.0.0b10.tar.gz",
"has_sig": false,
"md5_digest": "1e166e68790a5d01535ebad0f5a24009",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 29982,
"upload_time": "2023-06-21T07:42:21",
"upload_time_iso_8601": "2023-06-21T07:42:21.460965Z",
"url": "https://files.pythonhosted.org/packages/ed/06/c244dfd4c3c5ea63e0b7f17172bf9813da2edb5227cc1a8b4df65d99a903/vmt-0.0.0b10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-21 07:42:21",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": true,
"codeberg_user": "johndovern",
"codeberg_project": "vmt",
"lcname": "vmt"
}
