spotiplayer-pi/README.org

• README
  • What it does:
    • Project's scope
    • Features & Functionality
  • Get Started:
    • Hardware Requirements
    • Software Requirements
    • Install
    • Run
    • Configure
    • Develop
  • Code Philosophy / Style

README

Welcome welcome… This is a personal project to display the current playing Spotify track on a small LCD screen connected to a Raspberry Pi.

What it does:

Project's scope

This project aims to act as a view only display to showcase the current playing song on Spotify, it is built to support only one specific display and the Pi 5 hardware, no other platforms are intended to be supported soon.

Features & Functionality

This project uses the Spotify API to authenticate the user and pull live information about currently playing song, the information is then displayed in the screen. Features:

• Track Display: displays the track name, artists and album cover.
• Dynamic Progress bar: displays the track progress dynamically, to reduce API calls the bar assumes the track continues playing in-between requests, to smoothly contine updating the bar every refresh_interval
• Standby Screen: displays current time and QR code, the QR code can be set by the user to connect to a Spotify Speaker.
• Easy Config: all the parameters needed by the app running can be set in config.yaml, including the API polling rate interval, the display refresh interval, Spotify's app credential and the color scheme. The colors of all the UI components are exposed and controllable in this configuration file.

Get Started:

Hardware Requirements

This project is build for this specific screen, a 2" LCD SPi Display, compatible with different models of Raspberry Pi, this code is tested on a Pi 3b+ and a Pi 5.

Software Requirements

This project uses python3.11 and assumes you have it already installed. For development poetry is used to create a virtualenv and handle dependencies, ultimately the code must be run as sudo so the dependencies must be installed on the root python interpreter anyways, so the poetry virtualenv is for developement only.

Install

To install, start by cloning this repo with

git clone http://192.168.1.244:8080/barry/spotiplayer-pi.git
cd spotiplayer-pi

Then make sure you have poetry installed, to install on the Pi run: curl -sSL https://install.python-poetry.org | python3 -

poetry env use python3.11
poetry install
poetry shell

to activate the virtualenv every time use poetry shell. Now we need to install all the dependencies on the root python interpreter to run the script as the display GPiO connection needs privileges to be established. To do that we do:

sudo pip3 install requirements.txt

Run

To run the script there are two options, either from a CLI, with:

sudo python -m spotiplayer_pi.main

or as a systemd service, which guarantees that the script will be restarted if it fails, to activate it do:

# TODO

Configure

To configure the app's settings go to spotiplayer_pi/config.yaml, it contains all user modifiable settings, there you can set the progress bar refresh rate, the API polling rate and the color scheme of the play screen.

Develop

To contribute to the developement you will find some dev tools already implemented, to use them first install the extra dependencies with:

poetry install --with dev

Now you have access to pre-commit with the following hooks:

• ruff: format and lint .py files
• tests: run all tests in tests/
• requirements: checks if the output of poetry export matches requirements.txt

Only if all checks pass it is possible to make a commit

Code Philosophy / Style