{"id":15346729,"url":"https://github.com/centic9/headset-charge-indicator","last_synced_at":"2025-10-17T12:16:36.160Z","repository":{"id":45011921,"uuid":"259593732","full_name":"centic9/headset-charge-indicator","owner":"centic9","description":"A simple app-indicator for GNOME desktops to display the battery charge of some wireless headsets which also allows to control some functions like LEDs, sidetone and others.","archived":false,"fork":false,"pushed_at":"2024-04-30T02:57:06.000Z","size":73,"stargazers_count":136,"open_issues_count":3,"forks_count":18,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-07T12:22:32.050Z","etag":null,"topics":["app-indicator","arctis7-controls","corsair-devices","corsair-void","headset","headset-control","headsetcontrol","headsets","steelseries"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/centic9.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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},"funding":{"github":"centic9"}},"created_at":"2020-04-28T09:39:36.000Z","updated_at":"2025-03-03T07:50:09.000Z","dependencies_parsed_at":"2024-10-30T09:16:19.402Z","dependency_job_id":null,"html_url":"https://github.com/centic9/headset-charge-indicator","commit_stats":{"total_commits":77,"total_committers":5,"mean_commits":15.4,"dds":0.1558441558441559,"last_synced_commit":"b37af6fdbaa1e523b16094d3b314cf19e98369a5"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/centic9/headset-charge-indicator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/centic9%2Fheadset-charge-indicator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/centic9%2Fheadset-charge-indicator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/centic9%2Fheadset-charge-indicator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/centic9%2Fheadset-charge-indicator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/centic9","download_url":"https://codeload.github.com/centic9/headset-charge-indicator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/centic9%2Fheadset-charge-indicator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271287619,"owners_count":24733424,"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","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"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":["app-indicator","arctis7-controls","corsair-devices","corsair-void","headset","headset-control","headsetcontrol","headsets","steelseries"],"created_at":"2024-10-01T11:26:20.583Z","updated_at":"2025-10-17T12:16:36.060Z","avatar_url":"https://github.com/centic9.png","language":"Python","funding_links":["https://github.com/sponsors/centic9"],"categories":[],"sub_categories":[],"readme":"[![Release](https://img.shields.io/github/release/centic9/headset-charge-indicator.svg)](https://github.com/centic9/headset-charge-indicator/releases)\n[![GitHub release](https://img.shields.io/github/release/centic9/headset-charge-indicator.svg?label=changelog)](https://github.com/centic9/headset-charge-indicator/releases/latest)\n[![Tag](https://img.shields.io/github/tag/centic9/headset-charge-indicator.svg)](https://github.com/centic9/headset-charge-indicator/tags)\n\nA simple app-indicator for GNOME desktops to provide support for controlling some features of\nvarious wireless headsets.\n\n![Screenshot](headset-charge-indicator.png)\n\nIt supports displaying the battery charge, turning on/off LEDs and adjusting the sidetone level of the microphone. \n\nIt additionally supports displaying the 'chat-mix' level of Steelseries Arctis headphones.\n\nIt uses the tool from https://github.com/Sapd/HeadsetControl/ for connecting to a number of\npopular headsets and fetches information for displaying in the app-indicator bar on the desktop.\n\nIf an additional external script is provided, it also allows to switch between sending sound to the soundcard or to\nthe Headset and record from the correct microphone.\n\n## Installation\n\nOn Ubuntu/Debian based distributions, install the following packages:\n\n    sudo apt-get install python3-gi libappindicator3-1 gnome-icon-theme gir1.2-ayatanaappindicator3-0.1\n\nOn Arch Linux, it should be sufficient to run the following steps:\n\n    sudo pacman -S libappindicator-gtk3 gnome-icon-theme\n\nOn Fedora, the following package installation were [reported](https://github.com/centic9/headset-charge-indicator/issues/17#issuecomment-1984196359) \nto make it work at least on Fedora 39:\n\n    sudo dnf install libindicator\n    sudo dnf install libayatana-appindicator-gtk3\n\nOn other distributions, you might need to install the corresponding package for `libindicator` or `ayatanaappindicator`. \nSometimes `pygobject` might also be needed, but other distributions are untested, PRs with more information welcome!\n\n### Building HeadsetControl\n\nFollow the instructions at https://github.com/Sapd/HeadsetControl/ for building the binary and\nnote down the path to it.\n\nYou can test the helper application manually via `headsetcontrol -b -c`, this should print the current\nbattery level to the console if your headset is supported.\n\n### Starting the AppIndicator automatically \n\nYou can use the provided script `install.sh` to create an auto-start entry to start up headset-charge-indicator\nwhenever the Desktop Environment is starting up.\n\n## Usage\n\nBuild/install the required executable `headseatcontrol` according to the instructions \nabove, then start the headset-charge-indicator via \n\n    python3 headset-charge-indicator.py\n\nA Headset-icon should appear in the area for app-indicators together with a percentage number.\n\nYou can optionally supply a path to the `headsetcontrol` binary.\n\nIf you provide a commandline argument `--switch-command`, an additional \"Switch\" menu will be added with \noptions to switch between Soundcard and some Headsets and USB devices. The provided application or script will be\ninvoked with \"1\" for soundcard, \"2\" for headset, \"3\" for an USB headset, \"4\" for a chat-device and \"5\" for Monitor Audio\n(it should be easy to adjust this for your devices).\n\nA script can for example use pactl and/or pacmd to send audio output to the correct endpoint\nas well as setting audio input to the correct microphone.\n\n### Commandline\n\n```\n$ ./headset-charge-indicator.py -h\nusage: headset-charge-indicator.py [-h] [--headsetcontrol-binary \u003cpath to headsetcontrol binary\u003e] [--switch-command \u003cdevice switch command\u003e] [--verbose]\n\n    Simple AppIndicator which uses the HeadsetControl application from https://github.com/Sapd/HeadsetControl/ for retrieving charge information for wireless headsets and displays it as app-indicator\n    \n    The application has two optional commandline arguments, one for the location of the HeadsetControl binary and one for a command to switch between Laptop, Headset and other devices.\n    \n\noptional arguments:\n  -h, --help            show this help message and exit\n  --headsetcontrol-binary \u003cpath to headsetcontrol binary\u003e\n                        Optional path to headsetcontrol binary\n  --switch-command \u003cdevice switch command\u003e\n                        Optional command to switch between Laptop, Headset and other devices\n  --verbose             Increase output verbosity\n```\n\n## Supported Headsets\n\nLook at the description of https://github.com/Sapd/HeadsetControl/, headset which support \nat least fetching battery information are supported here as well, other functionality will work \nif the headset supports it.\n\n## Supported Desktop Envrionemnts\n\nThe tool uses Python bindings for the GNOME appindicator functionality. So it is mainly supported \non this desktop environment. \n\nHowever some other Desktop environments have some support for appindicators, so it might be \npossible to run this tool on other desktop environments as well.\n\nCurrently known behavior/support:\n\n* GNOME: Works fully\n   * Note: On Debian/Ubuntu you might need to install package `gnome-shell-extension-appindicator`.\n   * On other distributions, you will need to install the KStatusNotifierItem/AppIndicator Support from\n   https://extensions.gnome.org/extension/615/appindicator-support/\n        * After installation run `gnome-shell-extension-prefs` and enable `KStatusNotifierItem/AppIndicator Support`\n* Cinnamon: Seems to work, but percentage is not displayed as part of the indicator-icon\n* KDE/Plasma: Seems to work, but percentage is not displayed as part of the indicator-icon\n* MATE: Runs, but does not display an icon\n* LXDE: Seems to work, but percentage is not displayed as part of the indicator-icon (tested on Ubuntu Focal and Debian Bullseye)\n* Budgie: Runs, but does not display an icon\n* XFCE: Runs, but indicator-icon only appears for a very short time and then disappears again\n* OpenBox: ??\n\nPlease let me know via an issue if you successfully run it on another desktop environment or know of\na way to make it run better on any of those desktop environments!\n\nThe fact that the percentage does not show up everywhere is somewhat documented at http://net3d.free.fr/html/AppIndicator-0.1.gir/AppIndicator.Indicator-label.html\n\n## Desupport of AppIndicator\n\nDebian is phasing out support for `libappindicator` in favour of `libayatana-appindicator`, see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=895037 and https://wiki.debian.org/Ayatana/IndicatorsTransition\n\nThis tool now has support for this so that it first tries to load the newer AyatanaAppIndicator system and only falls back to AppIndicator if necessary.\n\n## Development/Debugging\n\nThe following information was helpful in developing this tool:\n* https://wiki.ubuntu.com/DesktopExperienceTeam/ApplicationIndicators#Typical_usage_.28C_version.29\n* http://candidtim.github.io/appindicator/2014/09/13/ubuntu-appindicator-step-by-step.html\n* http://net3d.free.fr/html/AppIndicator-0.1.gir/AppIndicator.Indicator.html\n\nThe python application will print out some information to standard-output which may give some\nmore information if things go wrong.\n\n## Licensing\n\n* headset-charge-indicator is licensed under the [BSD 2-Clause License].\n\n[BSD 2-Clause License]: https://opensource.org/licenses/bsd-license.php\n\n## Like it?\n\nIf you like my software please star the repository.\n\nIf you find this application useful and would like to support it, you can [Sponsor the author](https://github.com/sponsors/centic9)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcentic9%2Fheadset-charge-indicator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcentic9%2Fheadset-charge-indicator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcentic9%2Fheadset-charge-indicator/lists"}