{"id":29311639,"url":"https://github.com/layercak3/mpv-notification-osd","last_synced_at":"2026-05-14T21:32:59.961Z","repository":{"id":302536913,"uuid":"1011347895","full_name":"layercak3/mpv-notification-osd","owner":"layercak3","description":"mpv desktop notification OSD for track changes or media key playback control","archived":false,"fork":false,"pushed_at":"2025-10-10T01:21:28.000Z","size":179,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-21T14:49:38.662Z","etag":null,"topics":["c","libnotify","linux","mpv","mpv-script","notifications"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/layercak3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-30T17:14:04.000Z","updated_at":"2025-10-10T01:21:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"43f4c45a-47dc-49de-abdc-1602e3c04efd","html_url":"https://github.com/layercak3/mpv-notification-osd","commit_stats":null,"previous_names":["layercak3/mpv-notification-osd"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/layercak3/mpv-notification-osd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layercak3%2Fmpv-notification-osd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layercak3%2Fmpv-notification-osd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layercak3%2Fmpv-notification-osd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layercak3%2Fmpv-notification-osd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/layercak3","download_url":"https://codeload.github.com/layercak3/mpv-notification-osd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layercak3%2Fmpv-notification-osd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33044110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["c","libnotify","linux","mpv","mpv-script","notifications"],"created_at":"2025-07-07T08:15:39.833Z","updated_at":"2026-05-14T21:32:59.943Z","avatar_url":"https://github.com/layercak3.png","language":"C","funding_links":[],"categories":["Other"],"sub_categories":[],"readme":"# mpv-notification-osd\n\nThis is a C plugin for mpv which provides a small OSD in a notification for\nfeedback while mpv is unfocused and the playing track changes or playback is\nremotely controlled from JSON IPC/MPRIS. It supports embedded and external cover\nart, as well as a preview thumbnail of the current time position of a video.\n\n## Requirements\n\n* mpv built with C plugins support\n* mpv client API header, make, pkgconf, C compiler\n* an XDG desktop notifications server\n* GLib\n* GdkPixbuf\n* libnotify\n* libswscale\n* GNU/Linux (pipe2, timerfd)\n\n## Usage\n\nRun `make` to build the plugin, then copy the resulting `notification-osd.so`\nfile to your scripts directory. Alternatively, you can run `make install` as\nroot to install to the system/DESTDIR or as non-root to install to\n`~/.config/mpv/scripts`.\n\nThere are a few options which can be configured using the script-opts facility.\nThey are documented in [Script options](#script-options). Make sure to use the\nclient name (i.e. `notification_osd.conf` instead of `notification-osd.conf`).\n\n## Cover art and thumbnails\n\nThe `screenshot-raw` command is run when a video track is loaded or video\nparameters change. For videos, this is also repeatedly run whenever\n`percent-pos` changes and the notification is open. So, the\nimage/video/lavfi-complex that is selected will be shown in the notification\nwith whatever filters or equalizer parameters it has (if any).\n\nThe screenshot is downscaled using libswscale preserving aspect ratio so that\nthe notification server can handle it quickly and without using a lot of CPU\ntime. By default, the maximum dimensions are 64x64 and the bicubic option is\nused.\n\n## Notification lifetime\n\nNotifications are only shown while the player is not considered to be \"focused\".\nCurrently, \"focused\" is defined as the `focused` property being true or the\nmouse being hovered over the window. The intent is that notifications don't need\nto be shown while the user is interacting with the player window, only when they\nare doing something else. There is also support to manually or externally\ndictate if the notification is shown using script messages.\n\nAfter a triggering property change or event occurs which opens the\nnotification, it will expire after 10 seconds by default. During this time, the\ntext in the notification and thumbnail preview will be updated as player\nproperties change. Because setting an expire time for the server would result in\nthe timer being reset on each update, an expire time isn't set and the\nnotification server should be configured to not set one for the \"mpv\" category.\nInstead, the plugin closes the notification itself using its own timer.\n\nThis means that dismissing it through the notification server can be futile if\nplayer properties change and the notification is immediately sent again soon\nafter dismissal. The plugin registers a script message `close` (see the [Script\nmessages](#script-messages) section) which can be used to tell the plugin that\nthe notification should be closed. You can configure your notification server to\nsend this script message instead of trying to dismiss it. For example, using\nmako:\n\n```\n[app-name=ampv]\non-button-right=exec ~/.local/bin/mpvctl ampv ic 'script-message-to notification_osd close'\non-touch=exec ~/.local/bin/mpvctl ampv ic 'script-message-to notification_osd close'\n```\n\n## Script messages\n\nThe following script messages will be acted upon:\n\n* `close`: Disarm the timer and close the notification.\n* `open`: Force the notification to stay open until the `close` message is sent.\n* `reload-config`: Reload the configuration file (and apply runtime options over\n  it).\n\n## Script options\n\nSome script options can be set using the script-opts facility. These can be\nchanged at runtime.\n\n* `expire_timeout` (integer): Seconds to wait before closing the notification\n  after opening it.\n* `ntf_app_icon` (string): Symbolic icon name or filename. If this is an empty\n  string, the app icon won't be sent. (default: mpv)\n* `ntf_category` (string): Notification category. If this is an empty string,\n  the category won't be sent. (default: mpv)\n* `ntf_urgency` (choice): Notification urgency from \"low\", \"normal\", or\n  \"critical\". If this is an empty string or an incorrect choice, \"low\" will be\n  used. (default: low)\n* `send_thumbnail` (boolean): Generate and send thumbnails. (default: yes)\n* `send_progress` (boolean): Set the `value` hint to the value of `percent-pos`\n  to add a progress bar/background. (default: yes)\n* `send_sub_text` (boolean): Send the current subtitle or lyric text in the body\n  (`sub-text` property). (default: yes)\n* `thumbnail_size` (integer): The maximum width or height that the scaled\n  thumbnail will have. The other dimension may be decreased to preserve aspect\n  ratio. You probably want to set this to the size that your notification server\n  displays thumbnails such that it doesn't perform any scaling itself. (default:\n  64)\n* `screenshot_flags` (string): Screenshot flags to submit to the\n  `screenshot-raw` command. You probably want to leave this as \"video\" for video\n  without subtitles or \"subtitles\" to include subtitles. See the mpv manual for\n  details. (default: video).\n* `thumbnail_scaling` (choice): Thumbnail scaling option from \"fast-bilinear\",\n  \"bilinear\", \"bicubic\", or \"lanczos\". See `enum SwsFlags` in swscale.h for\n  details. If this is an empty string or an incorrect choice, \"bicubic\" will be\n  used. (default: bicubic)\n* `disable_scaling` (boolean): Don't scale the thumbnail, and instead send the\n  screenshot directly to the notification server. This can be slow depending on\n  the notification server, and its scaling method will likely be lower quality.\n  (default: no)\n* `focus_manual` (boolean): Always consider the player to be focused,\n  effectively never showing the notification unless the script messages are used\n  to manually/externally show it. (default: no)\n* `perfdata` (boolean): Collects and prints some frame timing information mostly\n  related to screenshots. (default: no)\n\n## License\n\nGPL-3.0-or-later, see COPYING.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flayercak3%2Fmpv-notification-osd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flayercak3%2Fmpv-notification-osd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flayercak3%2Fmpv-notification-osd/lists"}