{"id":25275068,"url":"https://github.com/cohoe/maxime","last_synced_at":"2026-04-25T11:36:27.270Z","repository":{"id":140974486,"uuid":"91206829","full_name":"cohoe/maxime","owner":"cohoe","description":"Bluetooth connection handler for Fedora/PulseAudio","archived":false,"fork":false,"pushed_at":"2020-10-08T04:48:16.000Z","size":42,"stargazers_count":1,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-01T07:51:09.395Z","etag":null,"topics":["bluetooth","bose","dbus","fedora","pulseaudio"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cohoe.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":"2017-05-13T22:43:09.000Z","updated_at":"2021-01-26T18:53:41.000Z","dependencies_parsed_at":"2023-06-29T06:00:20.146Z","dependency_job_id":null,"html_url":"https://github.com/cohoe/maxime","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cohoe/maxime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohoe%2Fmaxime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohoe%2Fmaxime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohoe%2Fmaxime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohoe%2Fmaxime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cohoe","download_url":"https://codeload.github.com/cohoe/maxime/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohoe%2Fmaxime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32261117,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["bluetooth","bose","dbus","fedora","pulseaudio"],"created_at":"2025-02-12T14:49:16.405Z","updated_at":"2026-04-25T11:36:27.242Z","avatar_url":"https://github.com/cohoe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Maxime\n======\n\nA utility for sanely utilizing Bluetooth headphones with PulseAudio.\n\n## Background\nA friend of mine (Maxime) worked at Bose and got me a pair of QC35 heaphones.\nSpoiler alert: They're pretty great! Unfortunately three words that still\ncause old unix-beards blood pressure to rise: Linux, Bluetooth, Audio. Turns\nout this is still true.\n\nFedora 25 (at the time of this writing) supports Bluetooth audio devices\nout of the box, so getting audio out of them is pretty easy. But to\ncomplicate things, I use the LADSPA Equalizer Plugin to do some system-wide\nEQ (shut up all your audiophilites, I truly do not care). The plugin requires\ndefining a master sink in the configuration file. This hinder any automatic\nswitching between devices as the headphones come on and off.\n\nThis utility is built to deal with that case.\n\n## Primary Features\n* Automatic switching to/from headphones on (dis)connect.\n* Desktop notifications.\n* Resync audio stream.\n\n## Under the Hood\nMaxime listens to DBus for events, particularly when the headphones\n(dis)connect. It will then determine which outputs (only the EQ right now) \nit needs to reroute to (or from) the headphones.\n\nConnect management uses a wrapper around bluetoothctl to manage the connection\nstate of the wireless device. You must have already paired and trusted your\ndevice for this to work. Goes something like\n```\n~ # bluetoothctl\n[bluetooth]# pair DE:AD:BE:EF:CA:FE\n[bluetooth]# trust DE:AD:BE:EF:CA:FE\n```\n\n## Prerequisites\nSystem stuff\n* A Fedora-based linux box (it might work with others? idk)\n* PulseAudio\n* Bluez\n\nThe following python modules are needed (Fedora package names in ()'s):\n* dbus (dbus-python)\n* pexpect (python2-pexpect)\n* gobject-base (python-gobject-base)\n* pulsectl (No package available)\n\n## Installation\n\n1) Copy the ``maxime.ini.example`` to ``~/.config/maxime.ini`` and edit appropriately\n2) Copy the ``maxime.desktop`` to ``~/.config/autostart/`` (If you want it to start on boot)\n3) Copy the other desktop files to ``~/.local/share/applications``\n3) Copy the ``maxime.py`` to ``/usr/local/bin/maxime.py``\n\nYou can put it wherever you want, just check the path in the .desktop file.\n\n_Optional:_\nThe QC35's identify a computer by name, which with Linux defaults to the hostname. \nIf your system has a FQDN as a hostname (ie, ``hostname`` spits out something like \n``foo.example.com``). This can be obnoxious because the onboard speech engine has\nto say (or spell) out the entire name. You can shorten this by specifying a \n``PRETTY_HOSTNAME=something`` in ``/etc/machine-info`` and restarting the Bluetooth\nservice. See [this repo](https://github.com/cohoe/workstation/blob/master/roles/bluetooth/tasks/main.yml) for an example.\n\nNote that if you have already paired/trusted the headphones you'll need to wipe them out\nto change the registered name.\n\n## Usage\n```\nusage: maxime.py [-h] [-c CONFIG] [-d] [-l LOGFILE] [--route ROUTE]\n                 [--connect] [--disconnect] [--listen] [--toggle]\n                 [--reconnect] [--status]\n\nBluetooth/Pulse audio routing manager.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -c CONFIG, --config CONFIG\n                        path to configuration file (defaults to\n                        ~/.config/maxime.ini)\n  -d, --debug           enable debug logging\n  -l LOGFILE, --logfile LOGFILE\n                        path to log file (otherwise logs to STDOUT)\n  --route ROUTE         send audio to a device (wireless, headset, speakers)\n  --connect             trigger a wireless connect event\n  --disconnect          trigger a wireless disconnect event\n  --listen              Listen for events but do not act on them\n  --toggle              toggle between speakers/wireless\n  --resync              resync the wireless audio stream\n  --reconnect           reconnect the wireless device\n  --status              show the current output device\n```\n\n## Buttons\nSince the multi-function button is pretty useless on Linux, I'm going to\ntake its functions and use them for something useful.\n* Single-tap (XF86AudioPlay): Mute\n* Double-tap (XF86AudioNext): Switch to speakers\n* Triple-tap (XF86AudioPrev): Force-reconnect\n\nSee [this repo](https://github.com/cohoe/workstation/blob/master/roles/xfce/tasks/keyboard.yml) for implementation.\n\n## Problems\n### Crappy dial-up quality audio\nYour system probably enabled the HSP \"headset\" profile instead of the A2DP \"high quality audio\".\nYou can change this by opening pavucontrol (Pulse Volume Control), going to the Configuration\ntab and setting Profile for your device to \"High Fidelity Playback (A2DP Sink)\".\n\n### Audio not in sync\nBest thing to do is run ``maxime.py --resync`` and hope for the best. Maybe don't walk so far away\nand/or re-orient your antenna. Bluetooth kinda sucks.\n\n### No audio and/or controls not working\nThe QC35's can be connected to multiple devices at the same time. You probably have a device\nthat has taken precedence (usually the first one if you slide the BT switch on the headphones).\nUnfortunately Bose has not given you a sane way to easily disconnect someone from the device\nitself, so you have to do it from that device. ``maxime.py --disconnect``\n\n### You have too many desktop shortcut files\nLaunchy doesnt deal with multiple entries in desktop files well. Sorry bro.\n\n## ToDo\n* Does not error when device is not present. Should either barf or attempt to connect for you.\n* Errors should produce a notification\n* Switching profiles should reconnect\n* Specify wireless fallback device.\n* Multiple speakers???\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcohoe%2Fmaxime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcohoe%2Fmaxime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcohoe%2Fmaxime/lists"}