Spotify Mobile Lyrics API

This API overrides the Spotify API endpoint used in the Spotify mobile app to fetch lyrics for the currently playing song.

You can use this API in xManager to fetch lyrics without having a Spotify Premium account.

• Spotify Mobile Lyrics API
  • How it works
  • xManager
    • Patch xManager
      • Download the pre-patched releases
      • Manually patch xManager release
  • Public servers list
  • Server setup
    • Docker
    • Vercel
    • Cloudflare Workers
    • Node.js / Bun
  • Contributors
  • License

How it works

1. The Spotify mobile app sends a request to the Mobile Spotify API to get the lyrics for the currently playing song.

2. The official Mobile Spotify API endpoint is overridden in the app code to point to the modified API.

3. The modified API fetches the lyrics from the WEB API of Spotify, which doesn't require a Premium account.

4. The lyrics are returned in the correct format (Protobuf) to the Spotify mobile app.

5. The mobile app displays the lyrics.

xManager

Patch xManager

Note

The latest versions of xManager already have the lyrics patch applied.
If you have an older version or want to use a different server, you can patch it manually.

Download the pre-patched releases

Go to the releases page and download the latest release of Spotify patched with xManager and the Spotify Mobile Lyrics API.

Manually patch xManager release

The script patch:xmanager will automatically download the latest release of xManager and apply the lyrics patch.

npm run patch:xmanager -- --server "lyrics.natanchiodi.fr" --apk "Spotify v8.9.84.594 [xManager] (Merged).apk" --ks-file "keystore.jks" --ks-pass "******"

Script arguments:

• --server the lyrics API host (see Public servers list).
• --apk the path to the Spotify APK. If not provided, the script will download the latest release (user input required).
• --ks-file (optional) the path to the keystore file.
• --ks-pass (optional) the keystore password.

If no keystore is provided, the script will sign the APK with your username.

Public servers list

Server name	Host	Owner
Default	lyrics.natanchiodi.fr	Natan Chiodi
Team xManager	xmanager-lyrics.dev	xC3FFF0E
-	-	-
➕ Add your server	See Adding a public server

Server setup

Docker

You can run the API in a Docker container.

The container will expose the API on port 3000. You can change the port by changing the -p argument.

Environment variables:

• SP_DC the sp_dc cookie value from the Spotify Web Player (see Finding sp_dc).
• SSL_CERT (optional) the SSL certificate string.
• SSL_KEY (optional) the SSL key string.

You can also mount a volume to /usr/src/app/certs to provide the SSL certificate and key (cert.pem and private.key).

Example

1. Pull the image:

docker pull ghcr.io/natoune/spotify-mobile-lyrics-api:latest

2. Run the container:

docker run -d -p 443:3000 -e SP_DC=spotify-cookie  -v /path/to/certs:/usr/src/app/certs ghcr.io/natoune/spotify-mobile-lyrics-api:latest

Vercel

Warning

The Free plan of Vercel is rate-limited (see Limits).
It should be enough for personal use, but consider upgrading to a paid plan or using another provider if you need more requests.

You can deploy the API to Vercel with the following steps:

1. Click the "Deploy with Vercel" button.
2. Set the SP_DC environment variable to the sp_dc cookie value from the Spotify Web Player (see Finding sp_dc).
3. Set up the redis integration.
4. Deploy the API.

Cloudflare Workers

You can deploy the API to Cloudflare Workers with the following steps:

1. Install the Wrangler CLI.
2. Clone the repository:

git clone https://github.com/Natoune/SpotifyMobileLyricsAPI.git
cd SpotifyMobileLyricsAPI

3. Install the dependencies:

npm install

4. Copy the wrangler.example.toml file to wrangler.toml:

cp wrangler.example.toml wrangler.toml

5. Create a new KV namespace and add it to the wrangler.toml file:

npx wrangler kv namespace create sp_redis

wrangler.toml:

...

[[kv_namespaces]]
binding = "sp_redis"
id = "YOUR_KV_ID"

6. Add an SP_DC secret

Get the sp_dc cookie value from the Spotify Web Player (see Finding sp_dc) and set it as a secret:

npx wrangler secret put SP_DC

7. Deploy the API:

npx wrangler deploy

Node.js / Bun

You can run the API on your own server with Node.js or Bun.

1. Clone the repository:

git clone https://github.com/Natoune/SpotifyMobileLyricsAPI.git
cd SpotifyMobileLyricsAPI

2. Install the dependencies:

npm install

or

bun install

3. Set the environment variables:

.env:

# The API must be available over HTTPS on port 443.
# Change this value only if you are behind a reverse proxy.
PORT=443

# Find a detailed guide on how to get your Spotify SP_DC cookie here: https://github.com/akashrchandran/syrics/wiki/Finding-sp_dc
SP_DC=your-spotify-cookie

4. Set up SSL [REQUIRED]

You have multiple options to set up SSL:

• Use a reverse proxy like Nginx or Caddy.
• Use a service like Cloudflare.
• Use a certificate
  • Place the certificate and key at certs/private.key and certs/cert.pem.

5. Build and start the API:

npm run build
npm start

or

bun build
bun start

Contributors

• Natan Chiodi - Creator

If you want to contribute, please see the CONTRIBUTING.md file.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.