{"id":26271286,"url":"https://github.com/cavefire/pybose","last_synced_at":"2025-12-12T02:13:39.071Z","repository":{"id":274660278,"uuid":"923592843","full_name":"cavefire/pybose","owner":"cavefire","description":"Control your BOSE Soundbar / Speaker locally (not SoundTouch)","archived":false,"fork":false,"pushed_at":"2025-04-07T05:38:15.000Z","size":181,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-07T05:46:48.119Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/cavefire.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":"2025-01-28T14:27:19.000Z","updated_at":"2025-04-07T05:35:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"ee3e2637-5957-4acd-9e74-1cc62e506019","html_url":"https://github.com/cavefire/pybose","commit_stats":null,"previous_names":["cavefire/pybose"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavefire%2Fpybose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavefire%2Fpybose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavefire%2Fpybose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavefire%2Fpybose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cavefire","download_url":"https://codeload.github.com/cavefire/pybose/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251879555,"owners_count":21658771,"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":[],"created_at":"2025-03-14T06:19:12.313Z","updated_at":"2025-11-09T10:02:33.029Z","avatar_url":"https://github.com/cavefire.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unofficial Bose API for Soundbars and Speakers\n\n[![Python Tests](https://github.com/cavefire/pybose/actions/workflows/python-tests.yml/badge.svg)](https://github.com/cavefire/pybose/actions/workflows/python-tests.yml)\n\nThis Python project provides an unofficial API to control Bose Soundbars and Speakers locally. The API was reverse-engineered by analyzing the Bose app's API calls and is **not officially supported by Bose**. It allows users to interact with their Bose devices through local network communication and provides a basic feature set for device control.\n\nAlso check out my Homeassistant integration: [Bose-Homeassistant](https://github.com/cavefire/Bose-Homeassistant)\n\n### Tested Devices\n- Bose Soundbar Ultra\n- Bose Soundbar 900\n- Bose Music Amplifier\n- Bose Soundbar 700\n- Bose Portable Speaker\n\nOther Bose devices may also work, but they have not been tested.\n\n---\n\n## Installation\n\n```bash\npip install pybose\n```\n\n## Usage\n\n### BoseAuth\nBOSE decided that in order to control your devices locally (!) you still need to acquire a token from their cloud. This is done by using the `BoseAuth` class. \n\nSadly there is no official documentation about this (at least none I could find), so I had to reverse engineer the API calls the official app makes. \n\n**Note:** The token is a JWT with a limited lifetime and needs to be refreshed manually. Consider caching the token to reduce API calls.\n\n#### Usage of `BoseAuth`\n```python\nbose_auth = BoseAuth()\ncontrol_token = bose_auth.getControlToken(email, password)\n\naccess_token = control_token['access_token']\nrefresh_token = control_token['refresh_token']\n```\n\n---\n\n### BoseDiscovery\nAfter you got your access token, you can begin by discovering your devices on the network. Therefore you can use the `BoseDiscovery` class.\n\n```python\ndiscovery = BoseDiscovery()\ndevices = discovery.discover_devices()\nfor device in devices:\n    print(f\"GUID: {device['GUID']}, IP: {device['IP']}\")\n```\n\nYou will need not only the **IP**, but also the **GUID** to connect to the device.\n\n---\n\n### BoseDevice\nNow you are ready to finally control your speaker! You can use the `BoseSpeaker` class to interact with your device.\n\n```python\nbose = BoseSpeaker(\n    bose_auth=auth\n    device_id=\"your_device_GUID\",\n    host=\"your_device_IP\"\n)\n\nbose.attach_receiver(lambda data: print(f\"Received unsolicited message: {json.dumps(data, indent=4)}\"))\n\nawait bose.connect()\nresponse = await bose.set_power_state(True)\nawait bose.disconnect()\n```\n\nAfter attaching to the speaker, you can use the following functions:\n* get_capabilities\n* get_system_info\n* get_audio_volume\n* set_audio_volume\n* get_now_playing\n* get_bluetooth_status\n* get_power_state\n* set_power_state\n* pause\n* play\n* skip_next\n* skip_previous\n* get_device_id\n* subscribe\n* switch_tv_source\n* set_source\n* get_sources\n* get_audio_settings\n* set_audio_settings\n* get_accessories\n* get_battery_status\n\n**Note:** The device supports more. But for now, these are the only functions implemented. Feel free to add more, or open an issue if you have a specific need.\n\n## Limitations\n* **Unofficial API:** The API is not officially supported by Bose and may break at any time.\n* **Token Lifetime:** The token has a limited lifetime and needs to be refreshed manually.\n* **Rate Limiting:** The API may be rate-limited by Bose if too many requests are made in a short period of time.\n\n## Contributing\nThis project is a work in progress, and contributions are welcome!\nIf you encounter issues, have feature requests, or want to contribute, feel free to submit a pull request or open an issue.\n\nThe file `AvailableMethods.txt` contains a list of all available `resources` I could find.\nBest way to find out, what data these functions need, is to use the official app and sniff the network traffic. I used `Proxymon` for this. There should be a websocket connection to `ws://\u003cdevice_ip\u003e:8082` which contains all the data you need.\n\n## Wishlist\n\nThe first item on my wishlist is a **Homeassistant** integration. I am currently working on this here: [Bose-Homeassistant](https://github.com/cavefire/Bose-Homeassistant)\n\n**Other items on my wishlist:**\n\n- [x] Implement token refresh\n- [x] Implement groups\n- [x] Implement source (TV / Optical / AUX) switching\n- [ ] Implement source (Bluetooth) switching\n- [x] Implement equalizer settings\n- [x] Implement bass module settings\n- [x] Implement surround speaker settings\n\nAnd lastly, a way to not use the BOSE cloud at all would be nice. But I am not sure, if this is possible at all.\n\n## Disclaimer\nThis project is not affiliated with Bose Corporation. The API is reverse-engineered and may break at any time. Use at your own risk.\n\n**Be respectful and avoid spamming the API with unnecessary requests to ensure this project remains functional for everyone.**\n\n\n**To the BOSE legal team:**\n\nAll API keys used in this project are publicly available on the Bose website.\n\nThere was no need to be a computer specialist to find them, so: Please do not sue me for making people use their products in a way they want to.\n\nIf you have any issues with me publishing this, please contact me! I am happy to discuss this with you and make your products better.\n\n## License\nThis project is licensed under GNU GPLv3 - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcavefire%2Fpybose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcavefire%2Fpybose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcavefire%2Fpybose/lists"}