{"id":13896665,"url":"https://github.com/deficient/volume-control","last_synced_at":"2025-07-17T13:30:45.369Z","repository":{"id":146978247,"uuid":"12028092","full_name":"deficient/volume-control","owner":"deficient","description":"Volume control for awesome window manager","archived":true,"fork":false,"pushed_at":"2024-08-18T20:10:10.000Z","size":54,"stargazers_count":86,"open_issues_count":0,"forks_count":4,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-25T02:33:16.342Z","etag":null,"topics":["awesome-wm","volume-control","volume-percent-indicator","widget"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deficient.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2013-08-10T22:54:03.000Z","updated_at":"2024-08-18T20:13:24.000Z","dependencies_parsed_at":"2024-02-23T11:14:58.053Z","dependency_job_id":"1ec41c74-75e5-4131-8768-f5dad797d5c9","html_url":"https://github.com/deficient/volume-control","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/deficient/volume-control","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deficient%2Fvolume-control","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deficient%2Fvolume-control/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deficient%2Fvolume-control/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deficient%2Fvolume-control/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deficient","download_url":"https://codeload.github.com/deficient/volume-control/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deficient%2Fvolume-control/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265611081,"owners_count":23797809,"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":["awesome-wm","volume-control","volume-percent-indicator","widget"],"created_at":"2024-08-06T18:03:04.418Z","updated_at":"2025-07-17T13:30:45.103Z","avatar_url":"https://github.com/deficient.png","language":"Lua","funding_links":[],"categories":["Environment and System Related","Lua"],"sub_categories":["Multimedia"],"readme":"**This repository has been assimilated into** https://github.com/deficient/deficient\n\n## awesome.volume-control\n\nVolume indicator+control widget for awesome window manager.\n\n![Screenshot](/screenshot.png?raw=true \"Screenshot\")\n\n### Installation\n\nSimply drop the script into your awesome config folder, e.g.:\n\n```bash\ncd ~/.config/awesome\ngit clone https://github.com/deficient/volume-control.git\n```\n\nI recommend to also install the following:\n\n```bash\npacman -S pavucontrol       # open volume manager with middle/right click\npacman -S acpid             # instant status updates (acpi_listen)\nsystemctl enable acpid\n```\n\n\n### Usage\n\nIn your `~/.config/awesome/rc.lua`:\n\n```lua\n-- load the widget code\nlocal volume_control = require(\"volume-control\")\n\n\n-- define your volume control, using default settings:\nvolumecfg = volume_control({})\n\n\n-- add the widget to your wibox\n...\nright_layout:add(volumecfg.widget)\n...\n\n\n-- add key bindings\nlocal globalkeys = awful.util.table.join(\n    ...\n    awful.key({}, \"XF86AudioRaiseVolume\", function() volumecfg:up() end),\n    awful.key({}, \"XF86AudioLowerVolume\", function() volumecfg:down() end),\n    awful.key({}, \"XF86AudioMute\",        function() volumecfg:toggle() end),\n    ...\n)\n```\n\n### Known issues\n\nOne common pitfall is using the wrong sound device. On systems with pulseaudio,\nit's usually best to create the control with:\n\n```lua\nvolumecfg = volume_control {device=\"pulse\"}\n```\n\nOn some systems, clicking the widget will mute audio, however clicking it again\nwill only unmute *Master* while leaving other subsystems (Speaker, …) muted,\nsee e.g. [#10](https://github.com/deficient/volume-control/pull/10). This may\nbe fixed by setting the device to *pulse*, as described above.\n\nFor pre-2019 `alsa-utils`, if you have the `listen` enabled, unplugging USB\nheadphones sometimes causes the process that monitors for audio status changes\n(`alsactl monitor`) to spin at 100% CPU, see\n[#11](https://github.com/deficient/volume-control/issues/11). When this\nhappens, you can safely kill the process or restart awesome (`Mod4 + Control +\nR`). This bug was fixed in `alsa-utils 1.1.7`.\n\n### Constructor\n\nYou can specify any subset of the following arguments to the constructor.\nThe default values are as follows:\n\n```lua\nvolumecfg = volume_control({\n  device  = nil,            -- e.g.: \"default\", \"pulse\"\n  cardid  = nil,            -- e.g.: 0, 1, ...\n  channel = \"Master\",\n  step    = '5%',           -- step size for up/down\n  lclick  = \"toggle\",       -- mouse actions described below\n  mclick  = \"pavucontrol\",\n  rclick  = \"pavucontrol\",\n  listen  = false,          -- enable/disable listening for audio status changes\n  widget  = nil,            -- use this instead of creating a awful.widget.textbox\n  font    = nil,            -- font used for the widget's text\n  callback = nil,           -- called to update the widget: `callback(self, state)`\n  widget_text = {\n    on  = '% 3d%% ',        -- three digits, fill with leading spaces\n    off = '% 3dM ',\n  },\n  tooltip_text = [[\nVolume: ${volume}% ${state}\nChannel: ${channel}\nDevice: ${device}\nCard: ${card}]],\n})\n```\n\n### Mouse actions\n\nThe easiest way to customize what happens on left/right/middle click is to\nspecify additional arguments to the constructor. These can be of any of the\nfollowing kinds:\n\n- name of a member function: `\"up\"`, `\"down\"`, `\"toggle\"`, `\"mute\"`, `\"get\"`\n- command string to execute\n- a callable that will be called with the volume control as first parameter\n\nE.g.:\n\n```lua\nvolumecfg = volume_control({\n  lclick=\"toggle\",                        -- name of member function\n  mclick=TERMINAL .. \" -x alsamixer\",     -- command to execute\n  rclick=function(self) self:mute() end,  -- callable, equivalent to \"mute\"\n})\n```\n\n### Icon widget\n\nYou can use the module as a basis to implement your own volume widget. For\nexample, an icon widget can be created as follows:\n\n```lua\nlocal function get_image(volume, state)\n    local icondir = os.getenv(\"HOME\") .. \"/.local/share/icons/\"\n    if volume == 0 or state == \"off\"  then return icondir .. \"audio_mute.png\"\n    elseif volume \u003c= 33               then return icondir .. \"audio_low.png\"\n    elseif volume \u003c= 66               then return icondir .. \"audio_med.png\"\n    else                                   return icondir .. \"audio_high.png\"\n    end\nend\n\nlocal volume_widget = volume_control {\n    tooltip = true,\n    widget = wibox.widget.imagebox(),\n    callback = function(self, setting)\n        self.widget:set_image(\n            get_image(setting.volume, setting.state))\n    end,\n}\n```\n\nHowever, in this case, I recommend to use\n[pasystray](https://github.com/christophgysin/pasystray) instead.\n\n### Requirements\n\n* [awesome 4.0](http://awesome.naquadah.org/).\n* pavucontrol (optional)\n* acpid (optional)\n\nYou will also need `amixer` and `alsactl`, most likely your distro has a\npackage called `alsa-utils` that contains them.\n\nIf you are using `pipewire`, you have to configure it to manage clients\nusing the userspace component of ALSA. For example on Arch Linux, this can\nbe done by installing the package `pipewire-alsa`. For Debian, you can\nfollow the instructions provided in the\n[Debian Wiki](https://wiki.debian.org/PipeWire#For_ALSA).\n\nSimilarly, if you are using `pulseaudio`, you need to configure it to manage\nclients using the userspace component of ALSA. For Arch Linux, that means\ninstalling the package `pulseaudio-alsa`.\n\n\n### Alternatives\n\nIf you like a volume control with an icon instead of text, I suggest to use\n[pasystray](https://github.com/christophgysin/pasystray), which is a more\ncomprehensive solution and built for the systray (not awesome widget) with a\nmuch nicer menu.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeficient%2Fvolume-control","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeficient%2Fvolume-control","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeficient%2Fvolume-control/lists"}