{"id":24360603,"url":"https://github.com/brickfrog/aw-watcher-plex","last_synced_at":"2025-07-16T04:34:59.406Z","repository":{"id":272128713,"uuid":"915607862","full_name":"brickfrog/aw-watcher-plex","owner":"brickfrog","description":"Logs what you watch on Plex","archived":false,"fork":false,"pushed_at":"2025-01-13T09:56:18.000Z","size":26,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-14T10:53:36.554Z","etag":null,"topics":["activitywatch","activitywatch-watcher","plex","plex-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brickfrog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-12T10:24:39.000Z","updated_at":"2025-06-23T17:46:19.000Z","dependencies_parsed_at":"2025-01-12T11:29:20.089Z","dependency_job_id":"9996595b-c873-4811-a30e-d3fc430ed2fb","html_url":"https://github.com/brickfrog/aw-watcher-plex","commit_stats":null,"previous_names":["brickfrog/aw-watcher-plex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/brickfrog/aw-watcher-plex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brickfrog%2Faw-watcher-plex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brickfrog%2Faw-watcher-plex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brickfrog%2Faw-watcher-plex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brickfrog%2Faw-watcher-plex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brickfrog","download_url":"https://codeload.github.com/brickfrog/aw-watcher-plex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brickfrog%2Faw-watcher-plex/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265481852,"owners_count":23773964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["activitywatch","activitywatch-watcher","plex","plex-api"],"created_at":"2025-01-18T21:31:52.217Z","updated_at":"2025-07-16T04:34:59.386Z","avatar_url":"https://github.com/brickfrog.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aw-watcher-plex\n\nAn [ActivityWatch](https://activitywatch.net/) watcher for [Plex](https://www.plex.tv/) that tracks your media playback activity. Reports what's currently playing on your Plex server to ActivityWatch, including metadata like titles, genres, and playback state. \n\n[aw-watcher-spotify](https://github.com/ActivityWatch/aw-watcher-spotify) was used as a reference for this implementation and structure. Similar to that, since it's based on the Plex API it will record off-system events that interact with your Plex server.\n\nIf you only plan to use this for local device  media I would suggest using [aw-watcher-media-player](https://github.com/2e3s/aw-watcher-media-player) as it can capture a wide source of media and is probably preferred if you're only tracking one device (i.e. you're only using Plex on your desktop/laptop where the watcher is running).\n\n## Features\n\nTracks your Plex media consumption including:\n\n* Movie and TV show playback with comprehensive metadata including titles, years, genres, and content ratings\n* TV show specific information including show titles and season/episode numbers\n* Movie specific details such as studio information and ratings\n* Device and platform information for each playback session\n* Real-time playback state monitoring (playing/paused)\n\nExample of results (from a TV show):\n\n```json\n{\"id\":54612,\"timestamp\":\"2025-01-11T04:59:51.943Z\",\"duration\":5.025,\"data\":{\"contentRating\":\"TV-14\",\"device\":\"iPhone\",\"duration\":2732459,\"episode_number\":19,\"genres\":[],\"platform\":\"iOS\",\"player_state\":\"paused\",\"season_number\":5,\"show_title\":\"The X-Files\",\"summary\":\"Mulder is held hostage inside an office where a man claims his boss is a monster and has clouded all their minds while he turns them into zombies one by one, which is disbelieved until Mulder opens his mind and allows himself to see it too.\",\"title\":\"Folie à Deux\",\"type\":\"episode\",\"year\":1998}}\n```\n\n\n## Installation\n\n### Requirements\n\n* Python 3.12+\n* uv for package management\n* A Plex server\n\n### Install the package and dependencies\n\n```bash\ngit clone https://github.com/brickfrog/aw-watcher-plex\nuv venv ~/.local/share/venvs/aw-watcher-plex # or your preferred location for virtual environments\nuv tool install .  # This will install the executable to ~/.local/bin\n```\n\nMake sure `~/.local/bin` is in your PATH. You can add this to your shell's config file (e.g. `.bashrc` or `.zshrc`):\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n## Configuration\n\nLearn how to acquire your Plex authentication token (X-Plex-Token) by following the instructions in the documentation [here](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/).\n\nThe watcher reads its configuration from:\n\n```text\n~/.config/activitywatch/aw-watcher-plex/aw-watcher-plex.toml\n```\n\nConfigure your token and server settings:\n\n```toml\n[aw-watcher-plex]\npoll_time = 5.0\nbase_url = \"http://localhost:32400\"\ntoken = \"YOUR-PLEX-TOKEN-HERE\"\nlog_pauses = true # set to false to not log when paused\n```\n\n## Usage\n\nStart / test out the watcher by running:\n\n```bash\nuv run python aw_watcher_plex/main.py\n```\n\n### Automating\nIf it's on the path, it should be picked up by the ActivityWatch server. If not, you can run it as a system service.\n\nWhen installed via `uv tool install .`, the `aw-watcher-plex` command will be installed in `~/.local/bin`. Here's an example systemd service file, change the requires to as needed (e.g. if you're using awatcher instead of aw-server):\n\n```service\n[Unit]\nDescription=ActivityWatch Plex Watcher\nAfter=aw-server.service\nRequires=aw-server.service\nBindsTo=aw-server.service\n\n[Service]\nType=simple\nExecStart=/home/user/.local/bin/aw-watcher-plex\nRestart=always\nRestartSec=3\n\n[Install]\nWantedBy=default.target\n```\n\nThe watcher will:\n\n* Connect to your configured Plex server\n* Monitor all active playback sessions\n* Report detailed playback activity to ActivityWatch\n* Intelligently prioritize playing sessions over paused ones when multiple sessions exist\n\n## Development\n\n### Install development dependencies\n\n```bash\nuv pip install -e \".[dev]\"\n```\n\n### Run tests\n\n```bash\npytest\n```\n\n## Limitations\n\nThis is a basic implementation focused on single-user Plex servers. Current limitations include:\n\n* Only tracks the most recently active session at any given time\n* Prioritizes playing sessions over paused ones / still logs when paused - stops when closed\n* No support for music or photo libraries\n* Limited error handling capabilities\n* No multi-user support\n\n## Contributing\n\nThis watcher is in early development and welcomes contributions, particularly in these areas areas that address the limitations above / or those that figure out a more elegant metadata structure.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrickfrog%2Faw-watcher-plex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrickfrog%2Faw-watcher-plex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrickfrog%2Faw-watcher-plex/lists"}