{"id":24673800,"url":"https://github.com/thyraz/sonos-kids-controller","last_synced_at":"2025-10-08T08:31:26.137Z","repository":{"id":38991467,"uuid":"267955525","full_name":"Thyraz/Sonos-Kids-Controller","owner":"Thyraz","description":"Software for self made touchscreen jukeboxes for kids. Supports Spotify streaming and uses Sonos for audio output.","archived":false,"fork":false,"pushed_at":"2024-02-19T11:30:22.000Z","size":6676,"stargazers_count":156,"open_issues_count":31,"forks_count":31,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-09-11T23:32:38.994Z","etag":null,"topics":["audiobooks","kids","raspberry","raspberry-pi","raspberrypi","sonos","sonos-controller","sonos-controllers","sonos-kids-controller","spotify","spotify-api","spotify-web-api"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Thyraz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-05-29T21:09:26.000Z","updated_at":"2025-09-08T11:50:11.000Z","dependencies_parsed_at":"2023-02-18T14:30:26.539Z","dependency_job_id":"c0df676d-ccca-4615-9cc4-d7a7a94378ce","html_url":"https://github.com/Thyraz/Sonos-Kids-Controller","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Thyraz/Sonos-Kids-Controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thyraz%2FSonos-Kids-Controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thyraz%2FSonos-Kids-Controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thyraz%2FSonos-Kids-Controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thyraz%2FSonos-Kids-Controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Thyraz","download_url":"https://codeload.github.com/Thyraz/Sonos-Kids-Controller/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thyraz%2FSonos-Kids-Controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278913356,"owners_count":26067642,"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-10-08T02:00:06.501Z","response_time":56,"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":["audiobooks","kids","raspberry","raspberry-pi","raspberrypi","sonos","sonos-controller","sonos-controllers","sonos-kids-controller","spotify","spotify-api","spotify-web-api"],"created_at":"2025-01-26T11:14:02.186Z","updated_at":"2025-10-08T08:31:25.743Z","avatar_url":"https://github.com/Thyraz.png","language":"JavaScript","readme":"# Sonos-Kids-Controller\n\n## Content\n[About Sonos-Kids-Controller](#about-sonos-kids-controller)\\\n[Dependencies](#dependencies)\\\n[Usage](#usage)\\\n[Configuration](#configuration)\\\n[Adding Content](#adding-content)\\\n[Autostart](#autostart)\\\n[Update](#update)\\\n[Hardware Player](#hardware-player)\\\n[Raspberry Pi optimization](#raspberry-pi-optimization)\\\n[Alternative Installation using Docker](#docker)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/170099/89946592-7863e480-dc23-11ea-9634-3fd8ff55852b.jpg\" width=\"800\" height=\"450\"\u003e\u003cbr\u003e\n\n\u003cimg src=\"https://user-images.githubusercontent.com/170099/89946772-b82acc00-dc23-11ea-914e-d45263c50ab0.jpg\" width=\"800\" height=\"450\"\u003e\u003cbr\u003e\n\n\u003cimg src=\"https://user-images.githubusercontent.com/170099/89948614-b7476980-dc26-11ea-8ff7-65ab747e7bb0.png\" width=\"800\" height=\"480\"\u003e\u003cbr\u003e\n\n\u003cimg src=\"https://user-images.githubusercontent.com/170099/89948807-09888a80-dc27-11ea-86f2-60b15258a899.png\" width=\"800\" height=\"480\"\u003e\u003cbr\u003e\n\n\u003cimg src=\"https://user-images.githubusercontent.com/170099/89948825-14431f80-dc27-11ea-809a-607260fed229.png\" width=\"800\" height=\"480\"\u003e\u003cbr\u003e\n\n## About Sonos-Kids-Controller\nThis software can be used to create a touch-based Sonos controller for your kids.\n\nIt can also be used with Spotify Connect compatible devices instead of Sonos if you use [this software](https://github.com/amueller-tech/spotifycontroller) instead of the node-sonos-http-api discribed later in this document.\n\n*Sonos-Kids-Controller uses __TTS__ (text to speech) when you click on texts in the UI, so your kids don't have to aks you anymore about the name of a specific episode.*\n\nThe recommended use case is in combination with Spotify Premium, as it's web API allows you to add albums using artist and album name instead of cryptic album-IDs. It's also possible to add multiple albums with a single search query (e.g. all albums from a sepcific artist).\n\nBut you can also add albums from the local Sonos library (in case an album isn't available in your favorite streaming service), from Apple Music or from Amazon Music Unlimited by specifiying the corresponding album IDs. See the music services section about how to retrieve these IDs.\n\nThe software consists of 2 parts:\n* The server component, running in an node express environment. Handles the album library and serves the client component to the browser\n*  The client component, developed in Ionic/Angular, which can be opened in a browser\n\n## Dependencies\nThis software uses [node-sonos-http-api](https://github.com/Thyraz/node-sonos-http-api) to control your Sonos hardware. __So you need to have it running somewhere, for example on the same system as this software__.\\\nThis doesn't have to be the Pi itself, but should be possible too (if it can handle everything performance-wise without any lags).\n\n## Usage\nEnsure that you have Node.js and npm installed.\nAlso install [node-sonos-http-api](https://github.com/Thyraz/node-sonos-http-api) as described in the readme of the software. \nIf you plan on using Spotify, follow the instructions [here.](https://github.com/Thyraz/node-sonos-http-api#note-for-spotify-users)\n\nThen install this software from Github:\n```\nsudo npm install -g @ionic/cli\n\nwget https://github.com/Thyraz/Sonos-Kids-Controller/archive/master.zip\n\nunzip master.zip\n\nrm master.zip \n\ncd Sonos-Kids-Controller-master\n\nnpm install\n\nionic build --prod\n\n```\nCreate the configuration file by making a copy of the included example:\n```\ncd server/config\n\ncp config-example.json config.json\n```\nEdit the config file as discribed in the chapter [configuration](#configuration)\n\nThen start the software like this:\n```\nnpm start\n```\n\nAfter that open a browser window and navigate to \n```\nhttp://ip.of.the.server:8200\n```\nNow the user interface should appear\n\n## Configuration\n```\n{\n    \"node-sonos-http-api\": {\n        \"server\": \"127.0.0.1\",\n        \"port\": \"5005\",\n        \"rooms\": [\n            \"Livingroom\",\n            \"Kitchen\"\n        ]\n    },\n    \"spotify\": {\n        \"clientId\": \"your_id\",\n        \"clientSecret\": \"your_secret\"\n    }\n}\n```\nPoint the node-sonos-http-api section to the adress and the port where the service is running.\nThe rooms are the Sonos room names that you want to be allowed as target.\n\nRoom selection isn't implemented yet, so only the first room will be used at the moment.\n\nThe spotify section is only needed when you want to use Spotify Premium as source.\nThe id and the secret are the same values as entered in the node-sonos-http-api configuration as described [here.](https://github.com/Thyraz/node-sonos-http-api#note-for-spotify-users)\n\n## Adding Content\nThere's a hidden button in the root view on the right side of the top navigation bar.\nIf you click there, you should see an overlay lighting up.\nClick this button quickly 10 times to open the library editor.\n\nThen click the \"+\" button on the top right to add a new entry.\n\n### Local Sonos Library:\n* Enter artist name and album name exactly as it's displayed in the Sonos app.\n* Enter an artwork link for an artwork image (remember, you can open the UI on any browser, so you can use a desktop pc or an mobile phone to add items to the library and use copy and paste for artwork links.)\nA good source for album artworks is the iTunes Artwork Finder: https://bendodson.com/projects/itunes-artwork-finder/\n\n### Spotify Premium:\n* Enter artist and album name to add a single album\n* Add a query instead, to search for multiple albums\n* Album artwork will be automatically retreived from Spotify\n\nExamples for query strings:\n```\nartist:Max Kruse album:Urmel\n\nartist:Grüffelo\n\nartist:Benjamin Blümchen album:folge NOT gute-nacht\n\nartist:\"Super Wings\"\n```\n\nMore details on Spotify web API search querys:\nhttps://developer.spotify.com/documentation/web-api/reference/search/search/#writing-a-query---guidelines\n\n### Apple Music or Amazon Music Unlimited:\n* Enter artist name and album name as they should be displayed in the UI.\n* Enter the album ID which can be discovered as described here: https://github.com/jishi/node-sonos-http-api#spotify-apple-music-and-amazon-music-experimental\n* Enter an artwork link for an artwork image (remember, you can open the UI on any browser, so you can use a desktop pc or an mobile phone to add items to the library and use copy and paste for artwork links.)\nA good source for album artworks is the iTunes Artwork Finder: https://bendodson.com/projects/itunes-artwork-finder/\n\nPro Tip:\nAs Amazon and Apple don't provide a full public API to search for content like Spotify does, adding AlbumIDs and artwork links through the UI might be time consuming and complicated.\nyou can also edit the library by editing _server/config/data.json_ (created after you added the first content through the UI).\nThe structure should be self-explaining.\nJust be sure to shutdown Sonos-Kids-Controller before editing the file, as the software might otherwise overwrite your changes with an in-memory copy of the data.\nAlso a backup of the file might be a good idea, as the software might overwrite the file with an empty library on startup, when you have some syntax errors in your edits, preventing the data from loading.\n\n\n## Autostart\nI use pm2 as process manager for node.js projects.\nSo both services (node-sonos-http-api and Sonos-Kids-Controller) are startet on boot time in this case\n\n```\nsudo npm install pm2 -g\n```\nThen build a startup script for pm2 (don't run with sudo):\n```\npm2 startup\n```\nafter that pm2 should show you a command that has to be run as sudo to finish install the startup scripts.\nCopy and paste it into the terminal and execute it.\n\nthen in the directory of node-sonos-http-api:\n```\npm2 start server.js\npm2 save\n```\n\nagain in the directory of Sonos-Kids-Controller:\n```\npm2 start server.js\npm2 save\n```\n\nAfter a reboot, enter `pm2 list` in the terminal and you should see that the 2 services are running. \n\n## Update\nUpdating to a newer Sonos-Kids-Controller version works similar to the initial installation.\nExecute these commands, starting from the parent directory of you current _Sonos-Kids-Controller-master_ installation:\n```\nwget https://github.com/Thyraz/Sonos-Kids-Controller/archive/master.zip\n\nunzip master.zip\n\nrm master.zip \n\ncd Sonos-Kids-Controller-master\n\nnpm install\n\nionic build --prod\n\n```\nIf you run into out of memory erros during the build process, try to set a memory limit manually:\n\n```\nexport NODE_OPTIONS=--max-old-space-size=3072\n\nionic build --prod\n```\n\n## Hardware Player\nWhile you can simply run this software on any server supported by node.js and open it in the browser of your choice (as long as it isn't IE or Edge), the typical use case will be a small box powered by an Raspberry Pi and a capacitive touch screen.\n\nI recommend a 5\" touch screen with a resolution of 800x480, as you otherwise might have to edit the layout of the software.\n\n### Part List:\n\nHere's a list of what I bought for my player:\n* [Raspberry Pi 3b](https://www.amazon.de/gp/product/B01CD5VC92/)\n* [Micro SD card](#https://www.amazon.de/gp/product/B073JWXGNT/)\n* [Power Supply](https://www.amazon.de/gp/product/B07NW9NXGF/)\n* [Capacitive 5 inch touchscreen](https://www.amazon.de/gp/product/B07YCBWRQP/)\n* [Flat HDMI cable](https://www.amazon.de/gp/product/B07R9RXWM5/)\n* [Tilted micro USB cable](https://www.amazon.de/gp/product/B01N26RAL6/)\\\n(use a cutter knive to remove some of the isolation of the tilted connector to save some more height)\n* [Small kitchen storage box as case](https://www.amazon.de/gp/product/B0841PZZ2C/) (ATTENTION: you need the mid sized box: 15.8cm x 12cm)\n* The bottom part of a raspberry case like [this one](https://www.amazon.de/schwarz-Gehäuse-Raspberry-neueste-Kühlkörper/dp/B00ZHG7AP0/) where you can tighten the raspberry without the need to drill holes in the backside of the jukebox\n* Tesa Powerstrips to fix the raspberry inside the jukebox\n\n### Front Cover Cutout:\n\nAs first step, choose the position of the cutout for the touchscreen in the wooden front cover.\nPay attention how far the HDMI and USB connectors stick out of the touch screen.\nBecause of that you won't be able to center the touchscreen vertically in the front cover.\n\nAfter that I drilled 4 holes in each edge of the cutout.\nThen I used a fredsaw to remove the part between the holes.\nKeep the cutout a little bit smaller than the touchscreen, as working with a fredsaw might not be that precise.\n\nNow the hard part begins:\\\nTweak the shape of the cutout with a rasp until the touchscreen fits in tightly.\nThis might take a while and I recommend to hold the touchscreen and the cover in front of each other toward a light source from time to time, to see where you need to remove more of the wood.\n\nWhen the touchscreen fits into the cutout, use sand paper to smooth the surface. I started with grain size 80 and ended with 300.\nIf you want an uniform look, use the finer grained sandpaper also on the front surface of the wood and apply some wood oil everywhere for a consistant looking finish.\n\n### Assembly:\nCut off the connector of the power supply, and drill a hole for the cable in the back of the case.\nStick the cable through the hole and solder the connector back on.\n\nAssemble the Pi in the bottom part of the raspberry case and use the Powerstrips to attach it inside the box.\n\nIf the touchscreen isn't sitting tight enough in the cutout, use __short__ screws to attach it to the front cover.\nMaybe predrill the holes, so the wood won't crack.\n\nConnect the cables, insert the microSD card and you're done.\nThe wooden front cover should stick firmly if you press it onto the backside. I didn't need any screws to hold it in place.\nIf you need to open it again, push a knive between the front cover and the backside and use it as lever. \n\n### Kiosk Mode Installation\n\nUse raspbian light (currently Buster is the latest stable version as I write this readme) as we don't want to install the default desktop environment.\n\na) because we don't need it\\\nb) because our Ionic/Angular app will stress the Pi enough, so we want to avoid too much running services and RAM usage.\n\nedit the config.txt in the boot partition and add the following lines at the end to configure the display:\n```\nmax_usb_current = 1 \nHdmi_group = 2 \nHdmi_mode = 87 \nHdmi_cvt 800 480 60 6 0 0 0 \n```\nAfter the initial boot process, start `raspi-config` and configure:\n* Localisation options and keyboard layout\n* Configure Wifi\n* Enable SSH if you wish to be able to log into the box remotely\n* Disable HDMI overscan in the advanced option\n* Change user password for pi\n* In _Boot Options_ Select 'Desktop/CLI' and then 'Console Autologin' for automatic login of the user pi\n\nNow reboot the Pi. If everything worked, you should be logged into the terminal session without having to enter you password at the end the boot process.\n\nUpdate all preinstalled packages:\n```\nsudo apt-get update\nsudo apt-get upgrade\n\n```\nNow we install Openbox as a lightweight window manager:\n```\nsudo apt-get install --no-install-recommends xserver-xorg x11-xserver-utils xinit openbox\n```\nAnd Chromium as a browser:\n```\nsudo apt-get install --no-install-recommends chromium-browser\n```\n\nYou can now install node-sonos-http-api and Sonos-Kids-Controller on the Pi (as described in the previous chapters) if you don't want to run it on a different server.\nDepending on where the services are running edit the automatic startup of Openbox and Chromium in _/etc/xdg/openbox/autostart_ \n\n\n```\n# Disable screen saver / power management\nxset s off\nxset s noblank\nxset -dpms\n\n# Start Chromium\nsed -i 's/\"exited_cleanly\":false/\"exited_cleanly\":true/' ~/.config/chromium/'Local State'\nsed -i 's/\"exited_cleanly\":false/\"exited_cleanly\":true/; s/\"exit_type\":\"[^\"]\\+\"/\"exit_type\":\"Normal\"/' ~/.config/chromium/Default/Preferences\nchromium-browser --disable-infobars --kiosk 'http://url-to-sonos-kids-controller:8200'\n```\n\nNow Chromium should display our web app when Openbox is started.\nThe last thing to do is to start the X server automatically when the Pi is powered on.\nAs we already have automatic login in the terminal session,\nwe can use __.bash_profile__ for starting X.\nAppend the following line to the file:\n```\n[[ -z $DISPLAY \u0026\u0026 $XDG_VTNR -eq 1 ]] \u0026\u0026 startx -- -nocursor\n```\nThis starts X when the user logged into the first system terminal (which is the one autologin uses).\n\nRestart the pi to see if everything works.\n\nIf you see a bubble in Chromium after some time, about Chromium not beeing up to date, use this workaround from [StackOverflow](https://stackoverflow.com/questions/58993181/disable-chromium-can-not-update-chromium-window-notification) and execute the following command:\n```\nsudo touch /etc/chromium-browser/customizations/01-disable-update-check;echo CHROMIUM_FLAGS=\\\"\\$\\{CHROMIUM_FLAGS\\} --check-for-update-interval=31536000\\\" | sudo tee /etc/chromium-browser/customizations/01-disable-update-check\n```\n\n## Raspberry Pi optimization\n\nYou may perform the following changes to Rasperry Pi OS AT YOUR OWN RISK.\n\n#### Disable boot up messages\n\nAccording to the guide on the site https://florianmuller.com/polish-your-raspberry-pi-clean-boot-splash-screen-video-noconsole-zram you can disable the boot up messages by adding the following text to the file __/boot/cmdline.txt__ (no linefeed, no double space):\n\n```\n loglevel=0 plymouth.enable=0 vt.global_cursor_default=0 plymouth.ignore-serial-consoles splash fastboot noatime nodiratime noram\n```\n\n#### Log to ramdisk \n\nYou may add the folling lines to the file __/etc/fstab__ to write temporary files and log files to ram. Attention: they get lost with every reboot.\n\n```\ntmpfs    /tmp    tmpfs    defaults,noatime,nosuid,size=100m    0 0\ntmpfs    /var/tmp    tmpfs    defaults,noatime,nosuid,size=25m    0 0\ntmpfs    /var/log    tmpfs    defaults,noatime,nosuid,mode=0755,size=25m    0 0\n```\n\nThis will speed up the boot up process and helps to improve the lifetime of the SD card.\n\n#### Fixed IP-Adress\n\na fixed IP Adress will speed up the boot process by about 3-5 seconds. Add your details to __/etc/dhcpcd.conf__. For example:\n\n```\ninterface wlan0\nstatic ip_address=192.168.0.4/24    \nstatic routers=192.168.0.254\nstatic domain_name_servers=192.168.0.254 8.8.8.8\n```\n\n#### Overclocking CPU\n\nYou may consider overclock your hardware by add the following lines to __/boot/config.txt. THIS MAY HARM YOUR HARDWARE!\n\nExample for Raspberry 3B:\n```\n# Overclock CPU\narm_freq=1200\nover_voltage=4\ntemp_limit=75\ncore_freq=500\n\n# Overclock GPU\nh264_freq=333\navoid_pwm_pll=1\ngpu_mem=320\nv3d_freq=500\n\n# Overclock RAM\nsdram_freq=588\nsdram_schmoo=0x02000020\nover_voltage_sdram_p=6\nover_voltage_sdram_i=4\nover_voltage_sdram_c=4\n```\n\n#### Overclocking sd card\n\nIf you have a suitable SD Card you may consider overclock the SD card reader by add the following lines to __/boot/config.txt. THIS MAY HARM YOUR HARDWARE!\n\n```\ndtparam=sd_overclock=100\n```\n\n## Docker\nThere is now also an easy way to setup this software using Docker.\nThis avoids the compilation on small hardware.\n\nThe image is maintained by [stepman0](https://github.com/stepman0)\\\nGet it [here](https://github.com/stepman0/docker-sonos-kids-controller).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthyraz%2Fsonos-kids-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthyraz%2Fsonos-kids-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthyraz%2Fsonos-kids-controller/lists"}