sortifyr

command module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 27, 2025 License: GPL-3.0 Imports: 5 Imported by: 0

README

Sortifyr

A web application to help organize and automate your Spotify playlists.

  • Detect duplicate and unavailable tracks in playlists
  • Keep track of your all time listening history and playlist changes
  • Create one-way synchronized playlists links

Features

Playlists
Duplicate tracks

Find any duplicate track in a playlist. You can trigger an automatic deletion of any duplicate entries.

Playlist duplicate tracks

[!NOTE] Due to Spotify API limitations this will first delete every instance of the duplicate track in the playlist and afterwards add it back.

Unplayable tracks

Find any track that is no longer playable. This can happen because of various reasons, for example licensing issues.

These tracks are recognizable by being grayed out. Unfortunately due to Spotify API limitations these tracks cannot be deleted with API calls. You'll have to delete them manually. The easiest way to find them is by sorting a playlist by artist. They will appear at the top.

Playlist unplayable tracks

Tracks
History

An overview of your history. It will show any track that you listened to or was played in a jam that you were a part of.

A track is only counted as played after you listened to it for at least 20 seconds, however due to the internal workings of the application it can be up to 40 seconds before a track is considered played.

Track history

Recently added / removed

An overview of recently added and removed tracks from any playlist.

Track added

Directories
Directories

In the Spotify client you can organize your playlists in directories. However Spotify doesn't expose this information in their API.

You can manually mirror your directory structure if desired. The directory structure is used in other locations of the application.

Directory

Links

This is in all fairness a very niche feature. But it is the reason why I started this project.

Short

Links allow you to one-way synchronize playlists / directories.

Long

It's best explained with an example. This is a simplified version of my personal Spotify organize structure

Root/
  All/
    Genres/
      Pop
      Rock
    Instrument/
      Piano
      Guitar
  Good/
    Genres/
      Pop
      Rock
    Instrument/
      Piano
      Guitar

As you can see there are 2 main directories, All and Good. For the most part they mirror each other.

What I generally do, is when I discover a new song that I like I add it to the right playlist in my Good directory. Whenever I play some music I shuffle a playlist inside the Good directory. When I eventually grow tired of the track I simply delete it.

However I don't want it to be gone forever! That's where the All directory comes in. It contains any track I ever added to the Good directory. So when I delete something in the Good directory, I can still find it in the All directory.

I'm using links to automatically add any track I add in Good to the right playlist in All. On top of that I have a master playlist that contains every track in any other playlist.

Link

FAQ

Does it automatically modify my playlists?

Only if configured to do so. By default it only tracks your Spotify data.

However when starting a duplicate removal task or setting up links then it will modify playlists.

Can this get my Spotify account banned?

No. It uses the official Spotify Web API.

Spotify has very clear rules on what is allowed. If you have a reason to believe this project breaches any them please contact me personally or by creating an issue.

What's the worst that can happen to my playlists?

The absolute worst situation I can think of is that you misconfigure a link. And all that it'll do is add some unwanted tracks to a playlist.

Why are changes to my playlists not immediately reflected in Sortifyr?

Changes made to playlists in Spotify are not immediately reflected in the web API. It can take up to 10 minutes before the API returns the updated data.

Spotify App setup

[!IMPORTANT] A Spotify premium account is required

This web application requires you to have a Spotify Developer app, which provides the credentials needed for authentication.

  1. Go to the Spotify developers website.
  2. Open your profile menu -> Dashboard.
  3. Click Create App.
  4. Fill out the form. Pay attention to:
    • Redirect URIs:
      • Reverse Proxy: https://<domain>/api/auth/callback/spotify
      • Local: http://127.0.0.1:<port>/api/auth/callback/spotify (default production port: 8000, development: 3001)
    • Which API are you planning to use?:
      • Choose Web API
  5. After creation you can access your client ID and client secret.

[!WARNING] By default only the owner of the developer app can login. You can add up to 25 extra users in the Spotify app dashboard.

Production Deployment

  1. Copy docker-compose.prod.yml -> docker-compose.yml.
  2. Copy .env.prod.example -> .env.
  3. Create your Spotify app and fill in the environment variables.
  4. Run docker compose up -d.
  5. The server is reachable on port 8000.

To update:

docker compose pull
docker compose down
docker compose up -d
Manual Setup (Advanced)

The container image is published as: ghcr.io/topvennie/sortifyr.

Required additional services:

  • Postgres
  • Redis
  • S3 compatible storage

Configuration variables can be overridden via environment variables. Keys use uppercase and replace . with _ (e.g. redis.url -> REDIS_URL)

Search the codebase for config.Get to view available configuration settings. You will probably need to change a couple to use your own services.

Development

[!IMPORTANT] Due to Spotify redirect restrictions, authentication only works when visiting the website through 127.0.0.1:3000. Do not use localhost as it will fail to authenticate.

Quick Start
  1. Install the tools listed in the asdf file (if you have asdf run asdf install).
  2. Install make.
  3. Run make setup to install:
    • Backend tools: Air, Goose, Sqlc, Deadcode
    • Frontend dependencies
  4. Install the git hooks for code quality: git config --local core.hooksPath .githooks/.
  5. Copy .env.example -> .env.
  6. Create a Spotify app (see above).
  7. Fill in all .env values.
  8. Run database migrations: make migrate.
  9. Start the project: make watch.

Endpoints:

Makefile Commands

A makefile is used to simplify some tasks. For an overview of all commands see the makefile.

A few common commands:

Start the full stack

make watch

Starts backend + frontend with hot module reloading. (Requires restart after adding or removing dependencies).

Create a new migration

make create-migration

Prompts for a name and then creates a new migration under db/migrations. Edit the SQL, optionally add new queries under db/queries, then run:

make query

Update SQLC queries

make query

Parses migrations and queries to generated types SQL query code. The result can be found in pkg/sqlc.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
cmd
api command
internal
database/model
Package model contains all databank models
Package model contains all databank models
database/repository
Package repository interacts with the databank and returns models
Package repository interacts with the databank and returns models
server
Package server starts the server
Package server starts the server
server/api
Package api contains all api routes
Package api contains all api routes
server/dto
Package dto forms the bridge between the api data and the internal models
Package dto forms the bridge between the api data and the internal models
server/middlewares
Package middlewares contains the server middlewares
Package middlewares contains the server middlewares
server/service
Package service is the business logic connects the api with the internal mechanisms
Package service is the business logic connects the api with the internal mechanisms
spotify
Package spotify syncrhonizes our local database with the spotify api
Package spotify syncrhonizes our local database with the spotify api
spotify/api
Package api interacts with the spotify api
Package api interacts with the spotify api
task
Package task provides an interface to schedule background recurring tasks
Package task provides an interface to schedule background recurring tasks
pkg
config
Package config lets you retrieve config variables
Package config lets you retrieve config variables
db
Package db connects with the databank
Package db connects with the databank
logger
Package logger initiates a zap logger
Package logger initiates a zap logger
redis
Package redis connects to the redis db
Package redis connects to the redis db
storage
Package storage connects with a file / image storage
Package storage connects with a file / image storage
utils
Package utils contains various util functions
Package utils contains various util functions

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL