{"id":18746693,"url":"https://github.com/matrixeditor/bose-soundtouch-api","last_synced_at":"2026-02-13T23:34:28.764Z","repository":{"id":219877680,"uuid":"729857754","full_name":"MatrixEditor/bose-soundtouch-api","owner":"MatrixEditor","description":"A small python library written to interact with BOSE devices. ","archived":false,"fork":false,"pushed_at":"2024-08-09T18:34:26.000Z","size":55,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T16:21:25.751Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MatrixEditor.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":"2023-12-10T15:17:59.000Z","updated_at":"2024-08-25T19:10:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"bf408491-37d9-474f-9b9c-38fd74caad28","html_url":"https://github.com/MatrixEditor/bose-soundtouch-api","commit_stats":{"total_commits":7,"total_committers":2,"mean_commits":3.5,"dds":0.1428571428571429,"last_synced_commit":"7eea898d7ab48e3827034300e42762c208c3fe48"},"previous_names":["matrixeditor/bose-soundtouch-api"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fbose-soundtouch-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fbose-soundtouch-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fbose-soundtouch-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixEditor%2Fbose-soundtouch-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatrixEditor","download_url":"https://codeload.github.com/MatrixEditor/bose-soundtouch-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637795,"owners_count":21137538,"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":"2024-11-07T16:26:32.913Z","updated_at":"2026-02-13T23:34:28.703Z","avatar_url":"https://github.com/MatrixEditor.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bose-SoundTouch-API (boseapi)\n\n![LastEdit](https://img.shields.io:/static/v1?label=LastEdit\u0026message=03/06/2023\u0026color=9cf)\n![Status](https://img.shields.io:/static/v1?label=Status\u0026message=DRAFT\u0026color=orange)\n![Platform](https://img.shields.io:/static/v1?label=Platforms\u0026message=Linux|Windows\u0026color=yellowgreen)\n![PyPi](https://img.shields.io:/static/v1?label=PyPi\u0026message=0.2.0\u0026color=green)\n\nThis small project implements commands to interact with these devices. The API and some basic usage examples are provided in the [api-documentation](https://bose-soundtouch-api.readthedocs.io).\n\n## Installation\n\nThis module can be easily installed via pip:\n```bash\n$ python3 -m pip install boseapi\n```\n\n## Usage\n\n```python\nfrom boseapi.all import *\n\ndevice = new_device('127.0.0.1')\nclient = SoundTouchClient(device, errors='ignore')\n\n# fetch device's capabilities\ncapabilities = client.capabilities()\nif capabilities.wsapiproxy:\n      # Create and use a WebSocket client\n      ws_client = BoseWebSocket(device)\n      # Add a listener on an updated volume\n      ws_client.add_listener(nodes.volumeupdated, lambda xmlelement: print(xmlelement.tag))\n      ws_client.start_notification()\n\n# Get the current volume and appply a new value to it (0..100).\nvolume = client.volume()\n# client.set_volume(7)\n# client.set_volume(volume.actual_vol + 1) \n# has the same effect as\nclient.volume_up()\n\n# If media is currently played by the device:\nstatus = client.status()\nif status.play_status != 'PLAY_STATE':\n      # Play own media\n      item = ContentItem(src=Source.INTERNET_RADIO, location='4712')\n      client.play(item)\n\n# Load and select presets\npresets = client.listpresets()\nif len(presets) \u003e 0:\n      preset = presets[0]\n      client.select_preset(preset)\n\n# Multiroom functionality\ncurrent_zone = client.zone_status()\nif current_zone.masterid == None:\n      zone = Zone(device_id=device.device_id, ip=device.host)\n      \n      # Add different zone slaves (it is recommended to create new devices\n      # befor adding a zone slave.\n      device2 = boseapi.new_device('127.0.0.2')\n      slave = ZoneSlave(device_id=device2.device_id, ip_address=device2.host)\n      zone.append(slave)\n\n      # Create zone/ Add slaves/ Remove slaves\n      client.create_zone(zone)\n      client.remove_zone_slave([slave])\n      client.add_zone_slave([slave])\n\n# List all available UPnP MediaServers\nmedia_servers = client.media_servers()\nif len(media_servers) \u003e 0:\nfor server in media_servers:\n      print(server)\n\n# List all available sources\nsources = client.listsources()\nif len(sources) \u003e 0:\n# Get specific source items with the source name\nsource_item = sources['QPLAY']\n# or the index position\nsource_item2 = sources[0]\n\n# Select different input sources\nclient.select_source(Source.BLUETOOTH)\n\nif source_item.status == 'READY':\n      client.select_source(source_item.source)\n\n# make sure the node is available be fore fetching data\nif 'GET' in client.options(nodes.bass):\n      # manually fetch or set data\n      message = client.get(nodes.bass)\n      bass = Bass(message.response)\n      client.put(nodes.bass, '\u003cbass\u003e0\u003c/bass\u003e')\n```\n\n## Overview\n---\nStarting off with the used device and app to get the information used to write the code for this repository.\n\n\u003e `Bose SoundTouch 300` and the `SoundTouch` app by BOSE\n\nWhile capturing traffic of the BOSE device the following URL was requested when searching for a sofware update:\n\n      \u003e https://downloads.bose.com/updates/soundtouch\n\nThe request is forwarded to another backend which contains a XML-Document named `index.xml`. This file contains information about the locations of all available firmware upgrades. Since the device used here needs the `SoundTouch 30` firmware, the following link is used.\n\n      \u003e https://downloads.bose.com/ced/soundtouch/mr4_cdb9ab51/Update_ti_27.0.3.46298.4608935.scm.stu\n\nAfter downloading, a quick review with binwalk on the file:\n\n```console\n$ binwalk Update_ti_27.0.3.46298.4608935.scm.stu                                                 \n\nDECIMAL       HEXADECIMAL     DESCRIPTION\n--------------------------------------------------------------------------------\n312           0x138           ELF, 32-bit LSB executable, ARM, version 1 (SYSV)\n[...]\n13932404      0xD49774        UBI erase count header, version: 1, EC: 0x0, VID header offset: 0x800, data offset: 0x1000\n[...]\n```\n\nThe only interesting line in the binwalk output contains information about an UBI image header. So, extract that file and decompress it with `ubidump`:\n\n```console\n$ ubidump -s . D49774.ubi\n```\n\nThis command creates a folder in the current directory where all the contents of this UBI document are stored. Files that contain information usable for creating this API are located in the following directory: `rootfs/opt/Bose/etc/`.\n\nThere are two files that configure operations that can be requested/ executed on the webserver (port `8090`). All operations contained in:\n\n```bash\nrootfs/opt/Bose/etc/HandCraftedWebServer-SoundTouch.xml \n# and\nrootfs/opt/Bose/etc/WebServer-SoundTouch.xml\n```\n\nwere implemented in this small library.\n\n---\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\u003c!-- LICENSE --\u003e\n---\n## License\n\nDistributed under the MIT License. See `MIT.txt` for more information.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixeditor%2Fbose-soundtouch-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrixeditor%2Fbose-soundtouch-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixeditor%2Fbose-soundtouch-api/lists"}