# Spotify Command Line
## Table of Contents
- [Introduction](#introduction)
- [Installation & Setup](#installation)
- [Installation](#installation)
- [Setup](#setup)
- [Uses](#uses)
- [Commands](#commands)
- [play](#play)
- [queue](#queue)
- [next](#next)
- [back](#back)
- [status](#status)
- [volume](#volume)
- [shuffle & repeat](#shuffle--repeat)
- [Quality Assurance](#quality-assurance)
- [Suggestions](#suggestions)
- [Contributing](#contributing)
- [License](#license)
## Introduction
A bit ago, I installed [ohmyzsh](https://github.com/ohmyzsh/ohmyzsh) onto my mac, and while looking at the plugins I stumbled across the [macos plugin](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/macos). There also was a sub-plugin in there to control [Spotify from the command line](https://github.com/ohmyzsh/ohmyzsh/blob/master/plugins/macos/spotify), but I didn't like it for two main reasons: it controlled Spotify through AppleScript as opposed to the Spotify API, and it didn't have the feature to queue songs. I would've been able to live with the first reason, since I only have my macbook, but not being able to queue songs was a deal breaker for me, as I'm not trying to delete my whole queue or switch to a different playlist every time I want to listen to a song. So I decided to make my own command line program to control Spotify! Unlike the ohmyzsh plugin, this program uses the Spotify API (through [Spotipy](https://github.com/spotipy-dev/spotipy)) to control Spotify, so any computer that has Python and Spotify installed can use this program.
## Installation & Setup
### Installation
To install, run the following command:
```bash
pip install spotifycl
```
You must already have Python installed on your computer.
### Setup
To setup the program, you need to have a spotify account (obviously), and you'll have to [create a new app](https://developer.spotify.com/dashboard/create) on the Spotify Developer Dashboard. Once you've created the app, find the Client ID and Client Secret in the app's settings, and then run the program in the terminal by typing `spotifycl` and follow the instructions. Once you've done that, you should be good to go!
## Uses
You can run the program by typing `spotifycl` into your terminal. You can also run the program with the `-h` or `--help` flag to get a list of all the commands and their descriptions. Spotify needs to be open and running on a device for the program to work.
Try to be as descriptive as possible when passing in the name of a playlist, album, artist, or song, because the program will find the first item that matches the name you pass in. And make sure you put quotes around any arguments that have any spaces. For example, if I try to play [Time by Pink Floyd](https://open.spotify.com/track/3TO7bbrUKrOSPGRTB5MeCz?si=99b89a567d294c81) by running [`spotifycl play time`](#play-song), it plays [Time of Our Lives by Pitbull](https://open.spotify.com/track/2bJvI42r8EF3wxjOuDav4r?si=f9995536185d4feb). While I love some Pitbull, that's not what I wanted to listen to. So if I run [`spotifycl play "time pink floyd"`](#play-song), it plays [Time by Pink Floyd](https://open.spotify.com/track/3TO7bbrUKrOSPGRTB5MeCz?si=99b89a567d294c81).
### Commands
#### play
There are 6 different ways to use the `play` command: [play](#play-1), [play song](#play-song), [play album](#play-album), [play artist](#play-artist), [play playlist](#play-playlist), and [play uri](#play-uri).
You can run any of them like so:
```bash
spotifycl play {--album|--band|--playlist|--uri} {song|album|band|playlist|uri}
```
##### play
This command will pause or play the current song depending on whether or not it's already playing.
```bash
spotifycl p
```
##### play song
This command will play the first song that matches the name of the song you pass in.
```bash
spotifycl p "song name"
```
##### play album
This command will play the first album that matches the name of the album you pass in.
```bash
spotifycl p -a "album name"
```
##### play artist
This command will play the first artist that matches the name of the artist you pass in.
```bash
spotifycl p -b "artist name"
```
##### play playlist
This command will play the first playlist that matches the name of the playlist you pass in.
```bash
spotifycl p -p "playlist name"
```
##### play uri
This command will play the song, album, artist, or playlist that matches the uri you pass in.
```bash
spotifycl p -u "uri"
```
#### queue
There are 4 different ways to use the `queue` command: [queue song](#queue-song), [queue album](#queue-album), [queue playlist](#queue-playlist), and [queue uri](#queue-uri).
You can run any of them like so:
```bash
spotifycl queue {--album|--playlist|--uri} {song|album|playlist|uri}
```
##### queue song
This command will queue the first song that matches the name of the song you pass in.
```bash
spotifycl q "song name"
```
##### queue album
This command will queue the first album that matches the name of the album you pass in.
```bash
spotifycl q -a "album name"
```
##### queue playlist
This command will queue the first playlist that matches the name of the playlist you pass in.
```bash
spotifycl q -p "playlist name"
```
##### queue uri
This command will queue the song, album, or playlist that matches the uri you pass in.
```bash
spotifycl q -u "uri"
```
#### next
This command will skip to the next song in the queue.
```bash
spotifycl {n|next}
```
#### back
This command will go back to the previous song in the queue.
```bash
spotifycl {b|back}
```
#### status
This command will print out the information about the current song.
```bash
spotifycl {s|status}
```
It prints out the song, artist, album, and the current time of the song.
#### volume
This command will either set the volume to the number you pass in, or it will print out the current volume.
```bash
spotifycl {v|volume} [number]
```
#### shuffle & repeat
These commands will either turn on or off shuffle and repeat.
```bash
spotifycl {t|toggle} {-s|--shuffle|-r|--repeat}
```
## Quality Assurance
All variable, function, class, module, & file names are written in [snake_case](https://en.wikipedia.org/wiki/Snake_case) to make sure everything is consistent, and all `const` variables are written in ALL-CAPS. The variable names are quite verbose, so it should be easy enough to understand what's going on.
If there are any other/better ways to check for quality assurance, please let me know in the [suggestions](https://github.com/Huckdirks/spotifyCL/discussions/new?category=suggestions)!
## Suggestions
If you have any suggestions about anything, please create a [new discussion in suggestions](https://github.com/Huckdirks/spotifyCL/discussions/new?category=suggestions).
## Contributing
Contributions are always welcomed! Look at [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
## License
The project is available under the [MIT](https://opensource.org/licenses/MIT) license.
Raw data
{
"_id": null,
"home_page": "https://github.com/Huckdirks/spotifyCL",
"name": "spotifyCL",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Spotify,API,Spotify API,Web API",
"author": "Huck Dirksmeier",
"author_email": "Huckdirks@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d7/34/c10457871b6e0620f72258081f805f1e9c3d40f732c54508805b086fa03d/spotifyCL-1.3.3.tar.gz",
"platform": null,
"description": "# Spotify Command Line\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Installation & Setup](#installation)\n - [Installation](#installation)\n - [Setup](#setup)\n- [Uses](#uses)\n - [Commands](#commands)\n - [play](#play)\n - [queue](#queue)\n - [next](#next)\n - [back](#back)\n - [status](#status)\n - [volume](#volume)\n - [shuffle & repeat](#shuffle--repeat)\n- [Quality Assurance](#quality-assurance)\n- [Suggestions](#suggestions)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Introduction\n\nA bit ago, I installed [ohmyzsh](https://github.com/ohmyzsh/ohmyzsh) onto my mac, and while looking at the plugins I stumbled across the [macos plugin](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/macos). There also was a sub-plugin in there to control [Spotify from the command line](https://github.com/ohmyzsh/ohmyzsh/blob/master/plugins/macos/spotify), but I didn't like it for two main reasons: it controlled Spotify through AppleScript as opposed to the Spotify API, and it didn't have the feature to queue songs. I would've been able to live with the first reason, since I only have my macbook, but not being able to queue songs was a deal breaker for me, as I'm not trying to delete my whole queue or switch to a different playlist every time I want to listen to a song. So I decided to make my own command line program to control Spotify! Unlike the ohmyzsh plugin, this program uses the Spotify API (through [Spotipy](https://github.com/spotipy-dev/spotipy)) to control Spotify, so any computer that has Python and Spotify installed can use this program.\n\n## Installation & Setup\n\n### Installation\n\nTo install, run the following command:\n\n```bash\npip install spotifycl\n```\n\nYou must already have Python installed on your computer.\n\n### Setup\n\nTo setup the program, you need to have a spotify account (obviously), and you'll have to [create a new app](https://developer.spotify.com/dashboard/create) on the Spotify Developer Dashboard. Once you've created the app, find the Client ID and Client Secret in the app's settings, and then run the program in the terminal by typing `spotifycl` and follow the instructions. Once you've done that, you should be good to go!\n\n## Uses\n\nYou can run the program by typing `spotifycl` into your terminal. You can also run the program with the `-h` or `--help` flag to get a list of all the commands and their descriptions. Spotify needs to be open and running on a device for the program to work.\n\nTry to be as descriptive as possible when passing in the name of a playlist, album, artist, or song, because the program will find the first item that matches the name you pass in. And make sure you put quotes around any arguments that have any spaces. For example, if I try to play [Time by Pink Floyd](https://open.spotify.com/track/3TO7bbrUKrOSPGRTB5MeCz?si=99b89a567d294c81) by running [`spotifycl play time`](#play-song), it plays [Time of Our Lives by Pitbull](https://open.spotify.com/track/2bJvI42r8EF3wxjOuDav4r?si=f9995536185d4feb). While I love some Pitbull, that's not what I wanted to listen to. So if I run [`spotifycl play \"time pink floyd\"`](#play-song), it plays [Time by Pink Floyd](https://open.spotify.com/track/3TO7bbrUKrOSPGRTB5MeCz?si=99b89a567d294c81).\n\n### Commands\n\n#### play\n\nThere are 6 different ways to use the `play` command: [play](#play-1), [play song](#play-song), [play album](#play-album), [play artist](#play-artist), [play playlist](#play-playlist), and [play uri](#play-uri).\n\nYou can run any of them like so:\n```bash\nspotifycl play {--album|--band|--playlist|--uri} {song|album|band|playlist|uri}\n```\n\n##### play\n\nThis command will pause or play the current song depending on whether or not it's already playing.\n\n```bash\nspotifycl p\n```\n\n##### play song\n\nThis command will play the first song that matches the name of the song you pass in.\n\n```bash\nspotifycl p \"song name\"\n```\n\n##### play album\n\nThis command will play the first album that matches the name of the album you pass in.\n\n```bash\nspotifycl p -a \"album name\"\n```\n\n##### play artist\n\nThis command will play the first artist that matches the name of the artist you pass in.\n\n```bash\nspotifycl p -b \"artist name\"\n```\n\n##### play playlist\n\nThis command will play the first playlist that matches the name of the playlist you pass in.\n\n```bash\nspotifycl p -p \"playlist name\"\n```\n\n##### play uri\n\nThis command will play the song, album, artist, or playlist that matches the uri you pass in.\n\n```bash\nspotifycl p -u \"uri\"\n```\n\n#### queue\n\nThere are 4 different ways to use the `queue` command: [queue song](#queue-song), [queue album](#queue-album), [queue playlist](#queue-playlist), and [queue uri](#queue-uri).\n\nYou can run any of them like so:\n```bash\nspotifycl queue {--album|--playlist|--uri} {song|album|playlist|uri}\n```\n\n##### queue song\n\nThis command will queue the first song that matches the name of the song you pass in.\n\n```bash\nspotifycl q \"song name\"\n```\n\n##### queue album\n\nThis command will queue the first album that matches the name of the album you pass in.\n\n```bash\nspotifycl q -a \"album name\"\n```\n\n##### queue playlist\n\nThis command will queue the first playlist that matches the name of the playlist you pass in.\n\n```bash\nspotifycl q -p \"playlist name\"\n```\n\n##### queue uri\n\nThis command will queue the song, album, or playlist that matches the uri you pass in.\n\n```bash\nspotifycl q -u \"uri\"\n```\n\n#### next\n\nThis command will skip to the next song in the queue.\n\n```bash\nspotifycl {n|next}\n```\n\n#### back\n\nThis command will go back to the previous song in the queue.\n\n```bash\nspotifycl {b|back}\n```\n\n#### status\n\nThis command will print out the information about the current song.\n\n```bash\nspotifycl {s|status}\n```\n\nIt prints out the song, artist, album, and the current time of the song.\n\n#### volume\n\nThis command will either set the volume to the number you pass in, or it will print out the current volume.\n\n```bash\nspotifycl {v|volume} [number]\n```\n\n#### shuffle & repeat\n\nThese commands will either turn on or off shuffle and repeat.\n\n```bash\nspotifycl {t|toggle} {-s|--shuffle|-r|--repeat}\n```\n\n## Quality Assurance\n\nAll variable, function, class, module, & file names are written in [snake_case](https://en.wikipedia.org/wiki/Snake_case) to make sure everything is consistent, and all `const` variables are written in ALL-CAPS. The variable names are quite verbose, so it should be easy enough to understand what's going on.\n\nIf there are any other/better ways to check for quality assurance, please let me know in the [suggestions](https://github.com/Huckdirks/spotifyCL/discussions/new?category=suggestions)!\n\n## Suggestions\n\nIf you have any suggestions about anything, please create a [new discussion in suggestions](https://github.com/Huckdirks/spotifyCL/discussions/new?category=suggestions).\n\n## Contributing\n\nContributions are always welcomed! Look at [CONTRIBUTING.md](CONTRIBUTING.md) for more information.\n\n## License\n\nThe project is available under the [MIT](https://opensource.org/licenses/MIT) license.\n",
"bugtrack_url": null,
"license": "",
"summary": "A command line interface for Spotify",
"version": "1.3.3",
"project_urls": {
"Homepage": "https://github.com/Huckdirks/spotifyCL"
},
"split_keywords": [
"spotify",
"api",
"spotify api",
"web api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ab11aeeca7ef23b2627282cf901e31b9b824b3f9b8e29de1b09f96a824a6f60e",
"md5": "bee5fcaea28c565af50c618ef66e9134",
"sha256": "113331ad388dacf8b4617091f0bd70b0a3fb00d84abc8d16bc79927daedd2580"
},
"downloads": -1,
"filename": "spotifyCL-1.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bee5fcaea28c565af50c618ef66e9134",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12345,
"upload_time": "2024-01-31T00:18:52",
"upload_time_iso_8601": "2024-01-31T00:18:52.972413Z",
"url": "https://files.pythonhosted.org/packages/ab/11/aeeca7ef23b2627282cf901e31b9b824b3f9b8e29de1b09f96a824a6f60e/spotifyCL-1.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d734c10457871b6e0620f72258081f805f1e9c3d40f732c54508805b086fa03d",
"md5": "cb4edad412a84c4ac2f0df8c81c86893",
"sha256": "c312361cee6a4a1c5ed20cb99b924cc5abcabbaa5ba079c644af0b7270ca6a79"
},
"downloads": -1,
"filename": "spotifyCL-1.3.3.tar.gz",
"has_sig": false,
"md5_digest": "cb4edad412a84c4ac2f0df8c81c86893",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9400,
"upload_time": "2024-01-31T00:18:54",
"upload_time_iso_8601": "2024-01-31T00:18:54.924344Z",
"url": "https://files.pythonhosted.org/packages/d7/34/c10457871b6e0620f72258081f805f1e9c3d40f732c54508805b086fa03d/spotifyCL-1.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-31 00:18:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Huckdirks",
"github_project": "spotifyCL",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "spotifycl"
}
JSON
