spotify-utils 2.1.0

An awesome and easy-to-use CLI for various Spotify® utility tasks

spotify-utils

An awesome and easy-to-use CLI for various Spotify® utility tasks!
Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Usage and examples
4. Contributing
5. License
6. Acknowledgments
7. Disclaimer

About The Project

There are many Spotify® clients out there; however, I didn't find one that really suited my needs, so I created this one. I want to create a Spotify® CLI which is easy-to-use, packed with useful functionalities and with a sophisticated documentation built-in.

Key features:

• Interactive TUI — a terminal user interface with tabs for browsing, exporting, and scanning duplicates
• Playlists
  • List information about playlists of the authenticated user in various output formats (Console, JSON)
  • Export playlist information in various formats (JSON, HTML)
  • Find duplicate tracks across all playlists

Of course, this CLI will not serve all needs, especially during development. I'll be adding more features in the near future. You may also suggest changes by forking this repo and creating a pull request or opening an issue.

(back to top)

Getting Started

Prerequisites

• Python 3.10+

Installation

pip install spotify-utils

Configuration

All methods require user authorization. You will need to register your app at Spotify Developer Dashboard to get the credentials necessary to make authorized calls. Click here to go to the step-by-step guide for creating a Spotify® application.

The CLI uses the Authorization Code Flow, which the user logs into once. It provides an access token that can be refreshed.

Environment variables are being used for configuration. In order for the CLI to function properly you need to provide the following environment variables (use export instead of SET on Linux):

set SPOTIFY_UTILS_CLIENT_ID='your-spotify-client-id'
set SPOTIFY_UTILS_CLIENT_SECRET='your-spotify-client-secret'
set SPOTIFY_UTILS_REDIRECT_URI='your-app-redirect-url'

In addition, the use of an .env file is supported:

SPOTIFY_UTILS_CLIENT_ID='your-spotify-client-id'
SPOTIFY_UTILS_CLIENT_SECRET='your-spotify-client-secret'
SPOTIFY_UTILS_REDIRECT_URI='your-app-redirect-url'

(back to top)

Usage and examples

In this section you can find usage examples of the CLI

Launch the interactive TUI

spotify-utils tui

The TUI provides three tabs:

• Playlists — browse all your playlists in a table; click a row to view its tracks
• Duplicates — scan your owned playlists and list any duplicate tracks
• Export — select a playlist (or all), choose JSON or HTML, and pick an output directory

Key bindings: Ctrl+L Playlists · Ctrl+D Duplicates · Ctrl+E Export · Ctrl+Q Quit

List all playlists of the current user in JSON format

spotify-utils playlists list --format json

[
  {
    "collaborative": false,
    "description": "Car Music Mix 2022 \ud83d\udd25 Best Remixes of Popular Songs 2022 EDM, Bass Boosted  by Rise Music",
    "external_urls": {
      "spotify": "https://open.spotify.com/playlist/0fM4AkfoGygOHVXjsNB7io"
    }
  }
]

Find duplicates across all playlists and display additional details:

spotify-utils playlists duplicates --verbose

Found 43 duplicate tracks across 20 playlists

Index	Name	Artists	Playlists	Track ID
0	Piercing Light	League of Legends, Mako	Rock, Sonos Mainstream	0163ud7I4Vb0ID5K7WBkq9
1	Edge Of The Earth	Thirty Seconds To Mars	Rock, Pop	0g9IOJwdElaCZEvcqGRP4b
...	...	...	...	...

Export playlists as HTML

spotify-utils playlists export --format html

Export specific playlist as JSON

spotify-utils playlists export --format json --id {PLAYLIST_ID}

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the Apache License 2.0. See LICENSE for more information.

(back to top)

Acknowledgments

• Typer
• Textual
• Spotipy
• Shields.io
• Choose an Open Source License

(back to top)

Disclaimer

This project isn’t endorsed by Spotify AB and doesn’t reflect the views or opinions of Spotify AB or anyone officially involved in producing or managing Spotify®

(back to top)