# mpv-history-daemon
This functions by connecting to socket files created by [`mpv-sockets`](https://github.com/seanbreckenridge/mpv-sockets). The `mpv` script there launches mpv with unique mpv sockets at `/tmp/mpvsockets/`.
For each `mpv` socket, this attaches event handlers which tell me whenever a file in a playlist ends, whenever I seek (skip), what the current working directory/path is, and whenever I play/pause an item. Once the `mpv` instance quits, it saves all the events to a JSON file.
Later, I can reconstruct whether or not a file was paused/playing based on the events, how long `mpv` was open, and which file was playing, in addition to being able to see what file/URL I was playing.
### Install
Requires `python3.8+`
pip install mpv-history-daemon
### Known Issues
For some reason I can never pinpoint, this stops working after a few days of continuous use (perhaps because of my laptop suspending?), so I wrap this with another script which restarts this every so often if there are no open `mpv` instances. I would recommend starting this by running:
```bash
mpv_history_daemon_restart "/your/data/dir"
```
## Usage
### daemon
```
Usage: mpv-history-daemon daemon [OPTIONS] SOCKET_DIR DATA_DIR
Socket dir is the directory with mpv sockets (/tmp/mpvsockets, probably) Data dir is the
directory to store the history JSON files
Options:
--log-file PATH location of logfile
--write-period INTEGER How often to write JSON data files while mpv is open
-s, --scan-time INTEGER How often to scan for new mpv sockets files in the SOCKET_DIR -
this is a manual scan of the directory every <n> seconds [env
var: MPV_HISTORY_DAEMON_SCAN_TIME; default: 10]
--socket-class-qualname TEXT Fully qualified name of the class to use for socket data, e.g.,
'mpv_history_daemon.daemon.SocketData'. This imports the class and
uses it for socket data.
--help Show this message and exit.
```
Some logs, to get an idea of what this captures:
```
1598956534118491075|1598957274.3349547|mpv-launched|1598957274.334953
1598956534118491075|1598957274.335344|working-directory|/home/sean/Music
1598956534118491075|1598957274.3356173|playlist-count|12
1598956534118491075|1598957274.3421223|playlist-pos|2
1598956534118491075|1598957274.342346|path|Masayoshi Takanaka/Masayoshi Takanaka - Alone (1988)/02 - Feedback's Feel.mp3
1598956534118491075|1598957274.3425295|media-title|Feedback's Feel
1598956534118491075|1598957274.3427346|metadata|{'title': "Feedback's Feel", 'album': 'Alone', 'genre': 'Jazz', 'album_artist': '高中正義', 'track': '02/8', 'disc': '1/1', 'artist': '高中正義', 'date': '1981'}
1598956534118491075|1598957274.342985|duration|351.033469
1598956534118491075|1598957274.343794|resumed|{'percent-pos': 66.85633}
1598956534118491075|1598957321.3952177|eof|None
1598956534118491075|1598957321.3955588|mpv-quit|1598957321.395554
Ignoring error: [Errno 32] Broken pipe
Connected refused for socket at /tmp/mpvsockets/1598956534118491075, removing dead socket file...
/tmp/mpvsockets/1598956534118491075: writing to file...
```
More events would keep getting logged, as I pause/play, or the file ends and a new file starts. The key for each JSON value is the epoch time, so everything is timestamped.
By default, this scans the socket directory every 10 seconds.
#### Watching the /tmp/mpvsockets/ directory
This does not come with a built-in inotify/directory watcher, but it does allow you to send a signal (in particular, `RTMIN`) to the daemon process to check if new files have been added.
So, I have a script like this (say, `mpv_signal_daemon`) which sends the signal:
```bash
pkill -f 'python3 -m mpv_history_daemon daemon' -RTMIN || true
```
And then I run [`watchfiles`](https://github.com/samuelcolvin/watchfiles) in the background like:
```bash
watchfiles mpv_signal_daemon '/tmp/mpvsockets/'
```
Whenever watchfiles sees a file added/modified/deleted, it sends a signal to the daemon, to recheck if there are new sockets to process.
Note: you don't have to use watchfiles, you're free to send the signal the daemon in whatever way works for you.
I personally run this with `--scan-time 30` and `watchfiles`. `watchfiles` will typically pick up all changes, but the poll is there just in case it fails or misses something
#### custom SocketData class
You can pass a custom socket data class with to `daemon` with `--socket-class-qualname`, which lets you customize the behaviour of the `SocketData` class. For example, I override particular events (see [`SocketDataServer`](https://github.com/seanbreckenridge/currently_listening/blob/main/currently_listening_py/currently_listening_py/socket_data.py)) to intercept data and send it to my [`currently_listening`](https://github.com/seanbreckenridge/currently_listening) server, which among other things displays my currently playing mpv song in discord:
### parse
The daemon saves the raw event data above in JSON files, which can then be parsed into individual instances of media:
```
Usage: mpv-history-daemon parse [OPTIONS] DATA_FILES...
Takes the data directory and parses events into Media
Options:
--all-events return all events, even ones which by context you probably
didn't listen to
--debug Increase log verbosity/print warnings while parsing JSON files
--help Show this message and exit.
```
As an example:
```json
{
"path": "/home/data/media/music/MF DOOM/Madvillain - Madvillainy/04 - Madvillain - Bistro.mp3",
"is_stream": false,
"start_time": 1614905952,
"end_time": 1614906040,
"pause_duration": 20.578377723693848,
"media_duration": 67.578776,
"media_title": "04 - Madvillain - Bistro.mp3",
"percents": [
[1614905960, 11.150022],
[1614905981, 11.151141]
],
"metadata": {}
}
```
This can also be called from python:
```python
>>> from pathlib import Path
>>> from mpv_history_daemon.events import history
>>> list(history([Path("1611383220380934268.json")]))
[
Media(path='/home/data/media/music/MF DOOM/Madvillain - Madvillainy/05 - Madvillain - Raid [feat. M.E.D. aka Medaphoar].mp3',
is_stream=False,
start_time=datetime.datetime(2021, 1, 23, 6, 27, tzinfo=datetime.timezone.utc),
end_time=datetime.datetime(2021, 1, 23, 6, 29, 30, tzinfo=datetime.timezone.utc),
pause_duration=0.0,
media_duration=150.569796,
media_title='Raid [feat. M.E.D. aka Medaphoar]',
percents=[(datetime.datetime(2021, 1, 23, 6, 27, 2, tzinfo=datetime.timezone.utc), 1.471624)]
metadata={})
]
```
### merge
After a while using this, I end up with thousands of JSON files in my data directory, which does use up some unnecessary space, and increases time to parse since it has to open thousands of files.
Those can be merged into a single file (which `parse` can still read fine) using the `merge` command:
```
Usage: mpv-history-daemon merge [OPTIONS] DATA_FILES...
merges multiple files into a single merged event file
Options:
--move DIRECTORY Directory to move 'consumed' event files to, i.e.,
a 'remove' these from the source directory once
they've been merged
--write-to PATH File to merge all data into [required]
--mtime-seconds INTEGER If files have been modified in this amount of time,
don't merge them
--help Show this message and exit.
```
Merged files look like:
```yaml
{ "mapping": {
"1611383220380934268.json":
{ "1619915695.2387643": { "socket-added": 1619915695.238762 } },
# other stuff...
} }
```
... saving the filename and the corresponding data from the original files
It doesn't merge any event files who've recently (within an hour) been written to, to avoid possibly interfering with current files the daemon may be writing to.
If you want to automatically remove files which get merged into the one file, you can use the `--move` flag, like:
```bash
mpv-history-daemon merge ~/data/mpv --move ~/.cache/mpv_removed --write-to ~/data/mpv/"merged-$(date +%s).json"
```
That takes any eligible files in `~/data/mpv` (merged or new event files), merges them all into `~/data/mpv/merged-...json` (unique filename using the date), and then moves all the files that were merged to `~/.cache/mpv_removed` (moving them to some temporary directory so you can review the merged file, instead of deleting)
My personal script which does this is synced up [here](https://github.com/seanbreckenridge/bleanser/blob/master/bin/merge-mpv-history)
Raw data
{
"_id": null,
"home_page": "https://github.com/seanbreckenridge/mpv_history_daemon",
"name": "mpv-history-daemon",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Sean Breckenridge",
"author_email": "\"seanbrecke@gmail.com\"",
"download_url": "https://files.pythonhosted.org/packages/b3/64/da19ae289816998ac0fc185885c0ffd63c1ed035a810df39e4075e51dcb2/mpv_history_daemon-0.2.6.tar.gz",
"platform": null,
"description": "# mpv-history-daemon\n\nThis functions by connecting to socket files created by [`mpv-sockets`](https://github.com/seanbreckenridge/mpv-sockets). The `mpv` script there launches mpv with unique mpv sockets at `/tmp/mpvsockets/`.\n\nFor each `mpv` socket, this attaches event handlers which tell me whenever a file in a playlist ends, whenever I seek (skip), what the current working directory/path is, and whenever I play/pause an item. Once the `mpv` instance quits, it saves all the events to a JSON file.\n\nLater, I can reconstruct whether or not a file was paused/playing based on the events, how long `mpv` was open, and which file was playing, in addition to being able to see what file/URL I was playing.\n\n### Install\n\nRequires `python3.8+`\n\n pip install mpv-history-daemon\n\n### Known Issues\n\nFor some reason I can never pinpoint, this stops working after a few days of continuous use (perhaps because of my laptop suspending?), so I wrap this with another script which restarts this every so often if there are no open `mpv` instances. I would recommend starting this by running:\n\n```bash\nmpv_history_daemon_restart \"/your/data/dir\"\n```\n\n## Usage\n\n### daemon\n\n```\nUsage: mpv-history-daemon daemon [OPTIONS] SOCKET_DIR DATA_DIR\n\n Socket dir is the directory with mpv sockets (/tmp/mpvsockets, probably) Data dir is the\n directory to store the history JSON files\n\nOptions:\n --log-file PATH location of logfile\n --write-period INTEGER How often to write JSON data files while mpv is open\n -s, --scan-time INTEGER How often to scan for new mpv sockets files in the SOCKET_DIR -\n this is a manual scan of the directory every <n> seconds [env\n var: MPV_HISTORY_DAEMON_SCAN_TIME; default: 10]\n --socket-class-qualname TEXT Fully qualified name of the class to use for socket data, e.g.,\n 'mpv_history_daemon.daemon.SocketData'. This imports the class and\n uses it for socket data.\n --help Show this message and exit.\n```\n\nSome logs, to get an idea of what this captures:\n\n```\n1598956534118491075|1598957274.3349547|mpv-launched|1598957274.334953\n1598956534118491075|1598957274.335344|working-directory|/home/sean/Music\n1598956534118491075|1598957274.3356173|playlist-count|12\n1598956534118491075|1598957274.3421223|playlist-pos|2\n1598956534118491075|1598957274.342346|path|Masayoshi Takanaka/Masayoshi Takanaka - Alone (1988)/02 - Feedback's Feel.mp3\n1598956534118491075|1598957274.3425295|media-title|Feedback's Feel\n1598956534118491075|1598957274.3427346|metadata|{'title': \"Feedback's Feel\", 'album': 'Alone', 'genre': 'Jazz', 'album_artist': '\u9ad8\u4e2d\u6b63\u7fa9', 'track': '02/8', 'disc': '1/1', 'artist': '\u9ad8\u4e2d\u6b63\u7fa9', 'date': '1981'}\n1598956534118491075|1598957274.342985|duration|351.033469\n1598956534118491075|1598957274.343794|resumed|{'percent-pos': 66.85633}\n1598956534118491075|1598957321.3952177|eof|None\n1598956534118491075|1598957321.3955588|mpv-quit|1598957321.395554\nIgnoring error: [Errno 32] Broken pipe\nConnected refused for socket at /tmp/mpvsockets/1598956534118491075, removing dead socket file...\n/tmp/mpvsockets/1598956534118491075: writing to file...\n```\n\nMore events would keep getting logged, as I pause/play, or the file ends and a new file starts. The key for each JSON value is the epoch time, so everything is timestamped.\n\nBy default, this scans the socket directory every 10 seconds.\n\n#### Watching the /tmp/mpvsockets/ directory\n\nThis does not come with a built-in inotify/directory watcher, but it does allow you to send a signal (in particular, `RTMIN`) to the daemon process to check if new files have been added.\n\nSo, I have a script like this (say, `mpv_signal_daemon`) which sends the signal:\n\n```bash\npkill -f 'python3 -m mpv_history_daemon daemon' -RTMIN || true\n```\n\nAnd then I run [`watchfiles`](https://github.com/samuelcolvin/watchfiles) in the background like:\n\n```bash\nwatchfiles mpv_signal_daemon '/tmp/mpvsockets/'\n```\n\nWhenever watchfiles sees a file added/modified/deleted, it sends a signal to the daemon, to recheck if there are new sockets to process.\n\nNote: you don't have to use watchfiles, you're free to send the signal the daemon in whatever way works for you.\n\nI personally run this with `--scan-time 30` and `watchfiles`. `watchfiles` will typically pick up all changes, but the poll is there just in case it fails or misses something\n\n#### custom SocketData class\n\nYou can pass a custom socket data class with to `daemon` with `--socket-class-qualname`, which lets you customize the behaviour of the `SocketData` class. For example, I override particular events (see [`SocketDataServer`](https://github.com/seanbreckenridge/currently_listening/blob/main/currently_listening_py/currently_listening_py/socket_data.py)) to intercept data and send it to my [`currently_listening`](https://github.com/seanbreckenridge/currently_listening) server, which among other things displays my currently playing mpv song in discord:\n\n\n\n### parse\n\nThe daemon saves the raw event data above in JSON files, which can then be parsed into individual instances of media:\n\n```\nUsage: mpv-history-daemon parse [OPTIONS] DATA_FILES...\n\n Takes the data directory and parses events into Media\n\nOptions:\n --all-events return all events, even ones which by context you probably\n didn't listen to\n --debug Increase log verbosity/print warnings while parsing JSON files\n --help Show this message and exit.\n```\n\nAs an example:\n\n```json\n{\n \"path\": \"/home/data/media/music/MF DOOM/Madvillain - Madvillainy/04 - Madvillain - Bistro.mp3\",\n \"is_stream\": false,\n \"start_time\": 1614905952,\n \"end_time\": 1614906040,\n \"pause_duration\": 20.578377723693848,\n \"media_duration\": 67.578776,\n \"media_title\": \"04 - Madvillain - Bistro.mp3\",\n \"percents\": [\n [1614905960, 11.150022],\n [1614905981, 11.151141]\n ],\n \"metadata\": {}\n}\n```\n\nThis can also be called from python:\n\n```python\n>>> from pathlib import Path\n>>> from mpv_history_daemon.events import history\n>>> list(history([Path(\"1611383220380934268.json\")]))\n[\n Media(path='/home/data/media/music/MF DOOM/Madvillain - Madvillainy/05 - Madvillain - Raid [feat. M.E.D. aka Medaphoar].mp3',\n is_stream=False,\n start_time=datetime.datetime(2021, 1, 23, 6, 27, tzinfo=datetime.timezone.utc),\n end_time=datetime.datetime(2021, 1, 23, 6, 29, 30, tzinfo=datetime.timezone.utc),\n pause_duration=0.0,\n media_duration=150.569796,\n media_title='Raid [feat. M.E.D. aka Medaphoar]',\n percents=[(datetime.datetime(2021, 1, 23, 6, 27, 2, tzinfo=datetime.timezone.utc), 1.471624)]\n metadata={})\n]\n```\n\n### merge\n\nAfter a while using this, I end up with thousands of JSON files in my data directory, which does use up some unnecessary space, and increases time to parse since it has to open thousands of files.\n\nThose can be merged into a single file (which `parse` can still read fine) using the `merge` command:\n\n```\nUsage: mpv-history-daemon merge [OPTIONS] DATA_FILES...\n\n merges multiple files into a single merged event file\n\nOptions:\n --move DIRECTORY Directory to move 'consumed' event files to, i.e.,\n a 'remove' these from the source directory once\n they've been merged\n --write-to PATH File to merge all data into [required]\n --mtime-seconds INTEGER If files have been modified in this amount of time,\n don't merge them\n --help Show this message and exit.\n```\n\nMerged files look like:\n\n```yaml\n{ \"mapping\": {\n \"1611383220380934268.json\":\n { \"1619915695.2387643\": { \"socket-added\": 1619915695.238762 } },\n # other stuff...\n } }\n```\n\n... saving the filename and the corresponding data from the original files\n\nIt doesn't merge any event files who've recently (within an hour) been written to, to avoid possibly interfering with current files the daemon may be writing to.\n\nIf you want to automatically remove files which get merged into the one file, you can use the `--move` flag, like:\n\n```bash\nmpv-history-daemon merge ~/data/mpv --move ~/.cache/mpv_removed --write-to ~/data/mpv/\"merged-$(date +%s).json\"\n```\n\nThat takes any eligible files in `~/data/mpv` (merged or new event files), merges them all into `~/data/mpv/merged-...json` (unique filename using the date), and then moves all the files that were merged to `~/.cache/mpv_removed` (moving them to some temporary directory so you can review the merged file, instead of deleting)\n\nMy personal script which does this is synced up [here](https://github.com/seanbreckenridge/bleanser/blob/master/bin/merge-mpv-history)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Daemon which connects to active mpv instances, saving a history of what I watch/listen to",
"version": "0.2.6",
"project_urls": {
"Homepage": "https://github.com/seanbreckenridge/mpv_history_daemon"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "225243743e34aef63bd4bef6556a212ea1f783941f8e135b90807ce370263d94",
"md5": "3d18dbcbcb3664c84e61d4dbd0f60688",
"sha256": "9bc0795b2e36408f6f09ddfc847d0eb527ca6527c58d5b3a5bb0b949aa2d8256"
},
"downloads": -1,
"filename": "mpv_history_daemon-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d18dbcbcb3664c84e61d4dbd0f60688",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25759,
"upload_time": "2024-02-15T01:42:41",
"upload_time_iso_8601": "2024-02-15T01:42:41.737556Z",
"url": "https://files.pythonhosted.org/packages/22/52/43743e34aef63bd4bef6556a212ea1f783941f8e135b90807ce370263d94/mpv_history_daemon-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b364da19ae289816998ac0fc185885c0ffd63c1ed035a810df39e4075e51dcb2",
"md5": "1a27a2ad13be9cdaaa4d6c525917e813",
"sha256": "bf5f73de166079845b060002a94f4404cccea1b4f9d7751e12d72bd25b9fc1c0"
},
"downloads": -1,
"filename": "mpv_history_daemon-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "1a27a2ad13be9cdaaa4d6c525917e813",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26391,
"upload_time": "2024-02-15T01:42:43",
"upload_time_iso_8601": "2024-02-15T01:42:43.252200Z",
"url": "https://files.pythonhosted.org/packages/b3/64/da19ae289816998ac0fc185885c0ffd63c1ed035a810df39e4075e51dcb2/mpv_history_daemon-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-15 01:42:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "seanbreckenridge",
"github_project": "mpv_history_daemon",
"github_not_found": true,
"lcname": "mpv-history-daemon"
}
JSON
