Listy

A web application that syncs your liked songs into a monthly playlist built with Go.

Features

• Spotify OIDC for authentication
• Automatically create a monthly playlist following the naming scheme YYYY MM
• Sync songs from your liked playlist to the current monthly playlist
• Reuse playlists following the same naming scheme
• Run the sync script as a one-time command (listy sync) or on a time (listy sync -r 5m)

Usage

Once you've deployed your Listy instance, all you need to do is head to http(s)://listy.example.com/auth/oidc/spotify/redirect where you will be redirected to Spotify for authorization, and then registered in Listy's database for monitoring. As long as the sync timer is running, or you setup a CRON job for the listy sync command, your liked songs will then automatically be synced with the current monthly playlist.

Deployment

Listy can be run as a self-hosted application as a Docker container or with Go installed.

Create a Spotify application

Head to the Spotify API dashboard and create your application. Call it "Listy" and take note of the generated client ID and secret.

Add the following redirect URI to the application to enable OIDC auth:

http(s)://listy.example.com/auth/oidc/spotify/callback

Listy configuration

Listy can be configured with environment variables or a config file, placed at the location of the binary or in one of the supported locations found in main.go.

The following configuration values are supported:

spotify:
  # Spotify OIDC client ID
  clientId: <SPOTIFY_CLIENT_ID>
  # Spotify OIDC client secret
  clientSecret: <SPOTIFY_CLIENT_SECRET>
mongodb:
  # MongoDB connection URI
  uri: <MONGODB_URI>
server:
  # session key used for cookie sessions, ideally a random string with at least 32 characters
  sessionKey: <SERVER_SESSION_KEY>
  # server scheme, either http or https
  scheme: <SERVER_SCHEME>
  # server host, such as localhost:5001 or listy.example.com
  host: <SERVER_HOST>

Support for environment variables

Listy supports environment variables corresponding to the names in the <> in the example file above.

With Docker compose

Listy can be deployed with Docker compose, and simply requires a MongoDB instance and the configuration file to work.

To deploy your Listy instance, copy the docker-compose.yml and optionally create a .env file for your sensitive values. The sample config is also provided at config.example.yml.

Finally, run the following in the folder where your docker-compose.yml and config.yml are:

$ docker compose up -d

Now, follow the usage instructions above to register to Listy.

Listy's sync script is already configured to run in a 5 minute interval in the sample Docker compose. See more below on other ways to run it.

listy sync

Besides the Go server (run with listy server run) the sync command provides most of the functionality in a self-contained worker that can either be run once or repeated by providing the --repeat flag which will be parsed by Go's time.ParseDuration() function. This will allow the sync script to run indefinitely.

Alternatively, you can setup the listy sync command as a CRON job or on Kubernetes as a CronJob resource.

License

Listy is licensed under the MIT license.

Contributions

Contributions are welcome, all code must simply pass CI. Contribution guidelines still WIP.

Roadmap

Some more features are planned, including:

• Optionally copying over songs from previous monthly lists
• Notifications
• Management UI