Unofficial Bose API for Soundbars and Speakers

This 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.

Also check out my Homeassistant integration: Bose-Homeassistant

Tested Devices

Bose Soundbar Ultra
Bose Soundbar 900
Bose Music Amplifier
Bose Soundbar 700
Bose Portable Speaker

Other Bose devices may also work, but they have not been tested.

Installation

pip install pybose

Usage

BoseAuth

BOSE 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.

Sadly 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.

Note: The token is a JWT with a limited lifetime and needs to be refreshed manually. Consider caching the token to reduce API calls.

Usage of `BoseAuth`

bose_auth = BoseAuth()
control_token = bose_auth.getControlToken(email, password)

access_token = control_token['access_token']
refresh_token = control_token['refresh_token']

BoseDiscovery

After you got your access token, you can begin by discovering your devices on the network. Therefore you can use the BoseDiscovery class.

discovery = BoseDiscovery()
devices = discovery.discover_devices()
for device in devices:
    print(f"GUID: {device['GUID']}, IP: {device['IP']}")

You will need not only the IP, but also the GUID to connect to the device.

BoseDevice

Now you are ready to finally control your speaker! You can use the BoseSpeaker class to interact with your device.

bose = BoseSpeaker(
    bose_auth=auth
    device_id="your_device_GUID",
    host="your_device_IP"
)

bose.attach_receiver(lambda data: print(f"Received unsolicited message: {json.dumps(data, indent=4)}"))

await bose.connect()
response = await bose.set_power_state(True)
await bose.disconnect()

After attaching to the speaker, you can use the following functions:

get_capabilities
get_system_info
get_audio_volume
set_audio_volume
get_now_playing
get_bluetooth_status
get_power_state
set_power_state
pause
play
skip_next
skip_previous
get_device_id
subscribe
switch_tv_source
set_source
get_sources
get_audio_settings
set_audio_settings
get_accessories
get_battery_status

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.

Development

Running Tests

This project includes both unit tests and integration tests.

Unit Tests

Unit tests mock external dependencies and can be run without credentials:

python -m pytest tests/unit/ -v

Integration Tests

Integration tests require real Bose account credentials and test against actual Bose APIs. Set the following environment variables:

export BOSE_EMAIL="your_email@example.com"
export BOSE_PASSWORD="your_password"
export BOSE_GWID="your_device_gwid"  # Optional, for product information tests

Run integration tests:

# Run all integration tests
python -m pytest tests/integration/ -v -m integration

# Run specific integration test
python -m pytest tests/integration/test_bose_auth_integration.py -v -m integration

Coverage Reports

Generate coverage reports in XML and JSON format:

python -m pytest tests/unit/ --cov=pybose --cov-report=xml --cov-report=json --cov-report=term

Limitations

Unofficial API: The API is not officially supported by Bose and may break at any time.
Token Lifetime: The token has a limited lifetime and needs to be refreshed manually.
Rate Limiting: The API may be rate-limited by Bose if too many requests are made in a short period of time.

Contributing

This project is a work in progress, and contributions are welcome! If you encounter issues, have feature requests, or want to contribute, feel free to submit a pull request or open an issue.

The file AvailableMethods.txt contains a list of all available resources I could find. Best 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://<device_ip>:8082 which contains all the data you need.

Wishlist

The first item on my wishlist is a Homeassistant integration. I am currently working on this here: Bose-Homeassistant

Other items on my wishlist:

Implement token refresh
Implement groups
Implement source (TV / Optical / AUX) switching
Implement source (Bluetooth) switching
Implement equalizer settings
Implement bass module settings
Implement surround speaker settings

And 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.

Disclaimer

This project is not affiliated with Bose Corporation. The API is reverse-engineered and may break at any time. Use at your own risk.

Be respectful and avoid spamming the API with unnecessary requests to ensure this project remains functional for everyone.

To the BOSE legal team:

All API keys used in this project are publicly available on the Bose website.

There 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.

If you have any issues with me publishing this, please contact me! I am happy to discuss this with you and make your products better.

License

This project is licensed under GNU GPLv3 - see the LICENSE file for details.

Metadata

Release files for pybose 2026.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pybose 2026.10.1
File	Size	Uploaded	Provenance
pybose-2026.10.1.tar.gz	35.5 kB	Oct 10, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pybose 2026.10.1
File	Interpreter	ABI	Platform	Reset
pybose-2026.10.1-py3-none-any.whl 34.7 kB Oct 10, 2026 Without provenance	Python 3	none	any	Details

Total release size: 70.2 kB

Release files / pybose-2026.10.1.tar.gz

Download URL	pybose-2026.10.1.tar.gz
Size	35.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`a04f3b73a1f009a824bf1481552eae2634fad51a97c143e58515b561ebda1cf6`
BLAKE2b-256 checksum How to use checksums	`a7a7dbdc2bb710776331b31d15ebd0ffe0b2ac54215b64e0e3a2e9fb2524449d`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`

Release files / pybose-2026.10.1-py3-none-any.whl

Download URL	pybose-2026.10.1-py3-none-any.whl
Size	34.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`95c34e86107621d6320ee2aab4335cd409f8b5dbd2f5dd5a6b53a7284d389112`
BLAKE2b-256 checksum How to use checksums	`fddfd2dbb724059e8e3d890011ae5a492feb6f8ea3d9c337dd287e7ad542a849`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`

Security for pybose 2026.10.1

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.