zlrclib 🎵

███████╗ ██╗      ██████╗   ██████╗ ██╗      ██╗ ██████╗ 
╚══███╔╝ ██║      ██╔══██╗ ██╔════╝ ██║      ██║ ██╔══██╗
  ███╔╝  ██║      ██████╔╝ ██║      ██║      ██║ ██████╔╝
 ███╔╝   ██║      ██╔══██╗ ██║      ██║      ██║ ██╔══██╗
███████╗ ███████╗ ██║  ██║ ╚██████╗ ███████╗ ██║ ██████╔╝
╚══════╝ ╚══════╝ ╚═╝  ╚═╝  ╚═════╝ ╚══════╝ ╚═╝ ╚═════╝ 

Overview

zlrclib is an open source firmware for requesting lyrics from lrclib.net and displaying them on tiny displays.

The firmware implements a lightweight client for the lrclib.net API, making it possible to fetch time-synced or unsynced lyrics directly from the internet. Lyrics can then be rendered on small displays that are commonly used in embedded projects.

Built on top of the Zephyr RTOS, zlrclib demonstrates how to integrate networking, HTTP APIs, and text rendering in resource-constrained environments.

zlrclib is licensed under the Apache-2.0 license. The documentation is licensed under the CC BY 4.0 license.

Firmware Features

The zlrclib firmware supports the following features, some of which depend on hardware support:

• [✔️] Wi-Fi provisioning via http server
• [✔️] Little Filesystem to store temporary data
• [✔️] GUI using lvgl library
• [✖️] Spotify Web API Integration

Getting Started

Before getting started, make sure you have a proper Zephyr development environment. Follow the official Zephyr Getting Started Guide.

Prerequisites

On the Linux Host, find the Zephyr net-tools project, which can either be found in a Zephyr standard installation under the tools/net-tools directory or installed stand alone from its own git repository:

git clone https://github.com/zephyrproject-rtos/net-tools
cd net-tools
make

To run with native_sim board first setup network interface with NAT

./net-setup.sh start --config nat.conf

Initialization

The first step is to initialize the workspace folder (workspace) where the zlrclib and all Zephyr modules will be cloned. Run the following command:

# initialize workspace for the zlrclib (main branch)
west init -m https://github.com/walidbadar/zlrclib --mr main workspace
# update Zephyr modules
cd workspace
west update

Building and running

To build the application, run the following command:

cd zlrclib
west build -b $BOARD app

where $BOARD is the target board.

You can use the zlrclibdk/esp32/procpu board found in this repository. Note that Zephyr sample boards may be used if an appropriate overlay is provided (see app/boards). Some other build configurations are also provided:

• overlay-debug.conf: Enable debug-friendly build
• overlay-shell.conf: Enable shell facilities

They can be enabled by setting OVERLAY_CONFIG, e.g.

west build -b $BOARD app -- -DOVERLAY_CONFIG=overlay-debug.conf

Once you have built the application, run the following command:

west flash

Recommended Disclaimer

zlrclib is an independent open-source project and is not affiliated with, endorsed by, or associated with lrclib.net.

This firmware simply communicates with the LRCLIB public API to fetch lyrics at runtime. It does not distribute, store, or bundle lyrics.

All song lyrics remain the copyrighted property of their respective owners. Users are responsible for ensuring their use of lyrics complies with applicable copyright laws and the terms of lrclib.net.