{"id":20340231,"url":"https://github.com/stefano-m/lua-media_player","last_synced_at":"2025-03-04T14:45:01.484Z","repository":{"id":96809162,"uuid":"65685999","full_name":"stefano-m/lua-media_player","owner":"stefano-m","description":"Media Player controls for Lua with Mpris and DBus","archived":false,"fork":false,"pushed_at":"2022-10-15T13:54:39.000Z","size":63,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-14T18:10:29.186Z","etag":null,"topics":["dbus","lua","media-player","mpris"],"latest_commit_sha":null,"homepage":"https://stefano-m.github.io/lua-media_player","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefano-m.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":"2016-08-14T20:54:51.000Z","updated_at":"2022-10-23T08:44:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"c2fbd39d-a665-4c20-adaf-500e67b75a64","html_url":"https://github.com/stefano-m/lua-media_player","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefano-m%2Flua-media_player","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefano-m%2Flua-media_player/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefano-m%2Flua-media_player/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefano-m%2Flua-media_player/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefano-m","download_url":"https://codeload.github.com/stefano-m/lua-media_player/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241867649,"owners_count":20033815,"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":["dbus","lua","media-player","mpris"],"created_at":"2024-11-14T21:20:20.660Z","updated_at":"2025-03-04T14:45:01.456Z","avatar_url":"https://github.com/stefano-m.png","language":"Lua","readme":"# Media Player controls for Lua with Mpris and DBus\n\nUse the DBus\n[Media Player Remote Interfacing Specification (Mpris)](https://specifications.freedesktop.org/mpris-spec/latest/)\nto control your media player (e.g.[ VLC](https://www.videolan.org/),\n[QuodLibet](https://quodlibet.readthedocs.io/)).\n\n# Installation\n\n## Using Luarocks\n\nProbably, the easiest way to install this widget is to use `luarocks`:\n\n    luarocks install media_player\n\nYou can use the `--local` option if you don't want or can't install\nit system-wide\n\nThis will ensure that all its dependencies are installed.\n\n## NixOS\n\nIf you are on NixOS, you can install this package from\n[nix-stefano-m-overlays](https://github.com/stefano-m/nix-stefano-m-nix-overlays).\n\n# Usage\n\n---------\n\n**NOTE**\n\nThis library leverages [GLib's GIO\nGDBusProxy](https://developer.gnome.org/gio/stable/GDBusProxy.html#GDBusProxy.description)\nobjects via\n[`dbus_proxy`](https://luarocks.org/modules/stefano-m/dbus_proxy). That means\nthat you **must** use the code inside a [GLib main event\nloop](https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#glib-The-Main-Event-Loop.description)\nfor it to work. For example, use it with [Awesome WM](https://awesomewm.org/)\nor create your own event loop.\n\n---------\n\nRequire the `media_player` module and then create a media player interface\nfor each player that implements the Mpris specification.\n\nWhen creating a media player with a given `NAME`, the module will\nattempt to connect to a DBus destination called `org.mpris.MediaPlayer2.\u003cNAME\u003e`.\n\nA media player is created with\n\n```lua\nMediaPlayer = require(\"media_player\")\nplayer = MediaPlayer:new(name)\n```\n\nUse the `is_connected` attribute on the player object to check whether the\ncorresponding application can controlled.\n\nFor example, say that we want to control `vlc`, but the application has not\nbeen started. In this case `is_connected` will be `false` and trying to access\nany attribute on the Proxy object will result in an error.\n\nInstead, when `is_connected` is `true`, you can, for example, use the\n`PlayPause`, `Stop`, `Previous` and `Next` methods to control the player.\n\nFor more detail, see also the\n[dbus_proxy](https://github.com/stefano-m/lua-dbus_proxy/) documentation.\n\nThe `Position` property and `position_as_str` method return the position of the\ntrack in microseconds and as `HH:MM:SS` respectively.\n\nThe `Metadata` property returns the current track's metadata in a table as per\nthe\n[metadata specification](https://www.freedesktop.org/wiki/Specifications/mpris-spec/metadata/).\n\nThe `info` method returns a subset of the metadata in a table with the following\nkeys:\n\n* `album`: name of the album\n* `title`: title of the song\n* `year`: song year\n* `artists`: comma-separated list of artists (may be just one artist)\n* `length`: total lenght of the track as `HH:MM:SS`\n\nSee the generated documentation for more detailed information.\n\n## An example using the Awesome Window Manager\n\nRequire the `media_player` module in your Awesome configuration file\n`~/.config/awesome/rc.lua` and then create a media player interface for each\nplayer that implements the Mpris specification.\n\nYou can create as many players as you want and bind them to different keys.\n\nIf you want to display information about the current track, you can use\n`Metadata` or `info` to extract it and then use it e.g. with\nAwesome's\n[`naughty.notify`](https://awesomewm.org/doc/api/modules/naughty.html#notify).\n\nFor example:\n\n```lua\nMediaPlayer = require(\"media_player\")\nquodlibet = MediaPlayer:new(\"quodlibet\")\nvlc = MediaPlayer:new(\"vlc\")\n```\n\nThen you can bind the keys.  In this example, the basic controls are set up,\nplus a notification and bindings to quit the application.\n\n```lua\nawful.util.table.join(\n  -- QuodLibet bound to the media keys\n  awful.key({}, \"XF86AudioPlay\", function () quodlibet.is_connected and quodlibet:PlayPause() end),\n  awful.key({}, \"XF86AudioStop\", function () quodlibet.is_connected and quodlibet:Stop() end),\n  awful.key({\"Control\"}, \"XF86AudioStop\", function () quodlibet.is_connected and quodlibet:Quit() end),\n  awful.key({}, \"XF86AudioPrev\", function () quodlibet.is_connected and quodlibet:Previous() end),\n  awful.key({}, \"XF86AudioNext\", function () quodlibet.is_connected and quodlibet:Next() end),\n  -- modkey + i shows useful information from QuodLibet\n  awful.key({modkey}, \"i\", function ()\n      local info = quodlibet.is_connected and quodlibet:info() or\n          {title = \"quodlibet\", album = \"not available\"}\n      naughty.notify({title=info.title, text=info.album})\n  end)\n  -- VLC bound to modkey + media keys\n  awful.key({modkey}, \"XF86AudioPlay\", function () vlc.is_connected and vlc:PlayPause() end),\n  awful.key({modkey}, \"XF86AudioStop\", function () vlc.is_connected and vlc:Stop() end),\n  awful.key({\"Shift\", \"Control\"}, \"XF86AudioStop\", function () vlc.is_connected and vlc:Quit() end),\n  awful.key({modkey}, \"XF86AudioPrev\", function () vlc.is_connected and vlc:Previous() end),\n  awful.key({modkey}, \"XF86AudioNext\", function () vlc.is_connected and vlc:Next() end)\n)\n```\n\nSince Awesome calls the functions without passing the object as first parameter,\nwe must wrap the call to the object's methods in an anonymous function.\n\n# Documentation\n\nThe documentation can be generated using [LDoc](http://stevedonovan.github.io/ldoc/).\nRunning `ldoc .` in the root of the repository will generate HTML documentation\nin the `docs` directory.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefano-m%2Flua-media_player","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefano-m%2Flua-media_player","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefano-m%2Flua-media_player/lists"}