{"id":19834503,"url":"https://github.com/thingpulse/esp32-spotify-remote","last_synced_at":"2025-08-13T17:16:15.277Z","repository":{"id":197403283,"uuid":"698583523","full_name":"ThingPulse/esp32-spotify-remote","owner":"ThingPulse","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-26T11:55:57.000Z","size":5204,"stargazers_count":12,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-26T17:37:04.876Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","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/ThingPulse.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-09-30T10:53:27.000Z","updated_at":"2025-07-26T11:49:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"d188704d-0329-4f02-8c0f-12264c8f3246","html_url":"https://github.com/ThingPulse/esp32-spotify-remote","commit_stats":null,"previous_names":["thingpulse/esp32-spotify-remote"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ThingPulse/esp32-spotify-remote","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingPulse%2Fesp32-spotify-remote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingPulse%2Fesp32-spotify-remote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingPulse%2Fesp32-spotify-remote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingPulse%2Fesp32-spotify-remote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThingPulse","download_url":"https://codeload.github.com/ThingPulse/esp32-spotify-remote/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingPulse%2Fesp32-spotify-remote/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270278702,"owners_count":24557182,"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-08-13T02:00:09.904Z","response_time":66,"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":[],"created_at":"2024-11-12T12:04:55.738Z","updated_at":"2025-08-13T17:16:15.255Z","avatar_url":"https://github.com/ThingPulse.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Color Kit Grande Spotify Controller\n\n[![Build Status](https://github.com/ThingPulse/esp32-spotify-remote/actions/workflows/main.yml/badge.svg)](https://github.com/ThingPulse/esp32-spotify-remote/actions)\n\nSpotify controller application for the [ThingPulse Color Kit Grande](https://thingpulse.com/product/esp32-wifi-color-display-kit-grande/).\n\n\u003c!-- Main image --\u003e\n\u003ca href=\"./images/HomeView.jpg\"\u003e\n  \u003cimg src=\"./images/HomeView.jpg\" alt=\"HomeView UI Example\" width=\"600\"/\u003e\n\u003c/a\u003e\n\n\u003c!-- Thumbnails --\u003e\n\u003cp\u003e\n  \u003ca href=\"./images/CoverArtView.jpg\"\u003e\n    \u003cimg src=\"./images/CoverArtView.jpg\" alt=\"Cover View\" width=\"200\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"./images/ClockView.jpg\"\u003e\n    \u003cimg src=\"./images/ClockView.jpg\" alt=\"Clock View\" width=\"200\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"./images/DiagnosticView.jpg\"\u003e\n    \u003cimg src=\"./images/DiagnosticView.jpg\" alt=\"Diagnostic View\" width=\"200\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Purpose of this project\n\nUsing the ThingPulse Spotify Controller you control a Spotify player (phone, browser, etc) from an Espressif ESP32 microcontroller.\nAlbum artwork as well as title and artist name are loaded from the Spotify Web API over WiFi and displayed on a color TFT touch-screen.\nThe currently playing song can be paused, resumed and skipped to the next or previous song in the playlist.\n\nA full OAuth 2.0 web flow is used to acquire the necessary access and refresh tokens to permit the user to control the player.\nIn order to run this project on your device, you will need to setup an application on your Spotify dashboard (instructions below).\n\n ## Features\n\n- **Spotify Playback Control**\n  - Play, pause, skip to next/previous track from the touch screen. ⚠️ Spotify requires a premium account for this!\n  - Control playback on any active Spotify Connect device linked to your account (e.g., phone, browser, smart speaker)\n\n- **Album Art Display**\n  - Downloads and displays album artwork via Spotify Web API\n  - Syncs background color with album art\n  - Caches artwork locally for performance\n\n- **Multiple UI Modes**\n  - Home view with track metadata and album art\n  - Cover Art only view\n  - Clock view with time and playback progress\n  - Supports 12-hour and 24-hour time formats\n  - Diagnostics view with system stats and Spotify state\n\n- **OAuth 2.0 Authorization Flow**\n  - Authentication and authorization (OAuth 2.0 flow) on device\n\n- **Designed for ESP32 + TFT Touch**\n  - Built using PlatformIO and Arduino\n  - Touch event handling for UI buttons and screen navigation\n  - Takes advantage of ESP32 dual-core architecture: UI logic runs on one core and background song and album art refreshing runs on the other\n\n- **Extensible Design**\n  - Modular architecture allows easy addition of new Views (UI screens)\n  - Built-in monitoring tools for measuring system performance and UI responsiveness\n  - Structured and tag-based logging system for easier debugging and analysis\n  - Optional `user.ini` file for easy credential and time zone management\n\n\n\u003c!--Design Context Diagram --\u003e\n\u003ca href=\"./documentation/SCDesign.jpg\"\u003e\n  \u003cimg src=\"./documentation/SCDesign.jpg\" alt=\"Design\" width=\"600\"/\u003e\n\u003c/a\u003e\n\n## Using the Spotify Controller\n\n- Tap the **Prev**, **Pause/Play**, and **Next** buttons to control music playback.\n- Tap the **album art** on the Home view to switch to the **Cover Art view**.\n- Tap the **clock** to switch to the **Clock view**.\n- Tap the **network status box** in the lower-right corner to open the **Diagnostics view**.\n- Tap the top-left corner for **Prev**, the top-center for **Pause/Play**, and the top-right for **Next** when using views other than Home.\n\n\u003e For detailed display logic and diagnostics layout, see `DiagnosticsView.cpp`.\n\n## Service level promise\n\n\u003ctable\u003e\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"https://thingpulse.com/assets/ThingPulse-open-source-community.png\" width=\"150\"\u003e\n\u003c/td\u003e\u003ctd\u003eThis is a ThingPulse \u003cem\u003ecommunity\u003c/em\u003e project. See our \u003ca href=\"https://thingpulse.com/about/open-source-commitment/\"\u003eopen-source commitment declaration\u003c/a\u003e for what this means.\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\n## Setup instructions\n\n### Precondition\n\nThe below instructions assume a properly configured Visual Studio Code installation with PlatformIO.\nSee our [instructions](https://docs.thingpulse.com/guides/esp32-color-kit-grande/#development-environment) if you need help with this.\n\n### Get access to the Spotify API\n\n1. Go to [https://developer.spotify.com/dashboard/login](https://developer.spotify.com/dashboard/login) and login to or sign up for the Spotify Developer Dashboard\n\n2. Select \"Create app\"\n\n   \u003cimg src=\"./images/SpotifyDashboard.png\" width=\"400\"\u003e\n\n3. Fill out the form. Give your new app a name you can attribute to this project.\nIt's safe to select \"I don't know\" for the type of application.\nAdd \"http://tp-spotify.local/callback/\" to the Redirect URIs section.\n\n   **NOTE** If you are running more than ThingPulse Spotify Remote in the same WiFi network, you should choose a unique name rather than \"tp-spotify\". Regardless of what you choose it has to reflect what you set for `SPOTIFY_ESPOTIFIER_NODE_NAME` in `spotify.h` in the project.\n\n   \u003cimg src=\"./images/SpotifyCreateApp.png\" width=\"400\"\u003e\n\n   **Don't forget to save your settings.**\n\n4. Set the unique Client ID and Client Secret as values for the respective variables in `src/spotify.h`.\n\n   \u003cimg src=\"./images/SpotifyClientId.png\" width=\"400\"\u003e\n\n### Filesystem setup\n\n5. Upload the file system to the device\n\n- Hit the PlatformIO icon on the navigation bar on the left side (alien face).\n\n- Select the Platform \u003e Upload Filesystem Image task.  Unless you later erase the flash or modify certain files, you only need to do this once if it succeeds. Pay attention to the output in the VS Code console that opens. If it reports any errors like e.g. if it cannot connect to the board or if stops midway, close VS Code completely, restart it, and then repeat the process.\n\n \u003cimg src=\"./images/platformio-filesystem.png\" width=\"400\"\u003e\n\n- If startup fails with the following message displayed: \"FATAL ERROR - Filesystem Not Initialized\", this step was not successful or done.\n\n### User settings\n\n6. The fastest way to get up and running is to open the `src/settings.h` file and adjust the handful of configuration parameters in the \"User settings\" section at the top. They are all documented inside the file directly. Everything should be self-explanatory.  The spotify settings were updated in step 4 above.\n\n \u003cimg src=\"./images/UserSettings.png\" width=\"400\"\u003e\n\nSee [full user settings documentation](./documentation/UserSettings.md) for details about all available fields, encryption options, and using `user.ini`.\n\n ### Upload code to device\n\n 7. Select the General \u003e Upload and Monitor task. You do this every time you change code or settings.h.\n\n  \u003cimg src=\"./images/platformio-task-upload.png\" width=\"400\"\u003e\n\nSee [instructions](https://docs.thingpulse.com/guides/esp32-color-kit-grande/#development-environment) if you encounter problems and need Trouble Shooting tips.\n\n## Tips and Known Issues\n\nTo see a list of tips and known issues, see [Tips and Known Issues](./documentation/TipsAndKnownIssues.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthingpulse%2Fesp32-spotify-remote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthingpulse%2Fesp32-spotify-remote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthingpulse%2Fesp32-spotify-remote/lists"}