|
1 | | -# Ironic Redistribution System |
| 1 | +# irs: The Ironic Repositioning System |
2 | 2 |
|
3 | | -[](http://www.gnu.org/licenses/gpl.html) |
4 | | -[](https://github.com/kepoorhampond/irs/stargazers) |
5 | | -[](https://saythanks.io/to/kepoorhampond) |
6 | | -[](https://pypi.python.org/pypi/irs) |
| 3 | +[](https://crystal-lang.org/) |
| 4 | +[](https://github.com/cooperhammond/irs/blob/master/LICENSE) |
| 5 | +[](https://saythanks.io/to/kepoorh%40gmail.com) |
7 | 6 |
|
8 | | -> A music downloader that understands your metadata needs. |
| 7 | +> A music scraper that understands your metadata needs. |
9 | 8 |
|
10 | | -A tool to download your music with metadata. It uses [Spotify](https://www.spotify.com/) for finding metadata and [Youtube](https://www.youtube.com/) for the actual audio source. You will need to have some Spotify tokens, the instructions to set them up are [here](https://github.com/kepoorhampond/irs#spotify-tokens). |
| 9 | +`irs` is a command-line application that downloads audio and metadata in order |
| 10 | +to package an mp3 with both. Extensible, the user can download individual |
| 11 | +songs, entire albums, or playlists from Spotify. |
11 | 12 |
|
12 | | -Works with Python 2 and 3. |
| 13 | +<p align="center"> |
| 14 | + <img src="https://i.imgur.com/7QTM6rD.png" height="400" title="#1F816D" /> |
| 15 | +</p> |
| 16 | +<p align="center" |
13 | 17 |
|
14 | | -## Install and Setup |
15 | | -``` |
16 | | -$ sudo pip install irs |
17 | | -$ irs --setup |
18 | | -``` |
| 18 | +[](https://forthebadge.com) |
| 19 | +[](https://forthebadge.com) |
| 20 | +[](https://forthebadge.com) |
| 21 | +</p> |
19 | 22 |
|
20 | | -**You will need to have some Spotify tokens, the instructions to set them up are [here](https://github.com/kepoorhampond/irs#spotify-tokens).** |
| 23 | +--- |
21 | 24 |
|
| 25 | +## Table of Contents |
22 | 26 |
|
23 | | -## Demo and Usages |
| 27 | +- [Usage](#usage) |
| 28 | + - [Demo](#demo) |
| 29 | +- [Installation](#installation) |
| 30 | + - [Pre-built](#pre-built) |
| 31 | + - [From source](#from-source) |
| 32 | + - [Set up](#setup) |
| 33 | +- [Config](#config) |
| 34 | +- [How it works](#how-it-works) |
| 35 | +- [Contributing](#contributing) |
24 | 36 |
|
25 | | -The usages can be found with the `-h` or `--help` flag: |
26 | | -``` |
27 | | -usage: irs [-h] [-S] [-a ARTIST] [-s SONG] [-A ALBUM] [-p PLAYLIST] |
28 | | - [-u USERNAME] [-o ORGANIZATION] |
29 | | -
|
30 | | -optional arguments: |
31 | | - -h, --help show this help message and exit |
32 | | - -S, --setup Run this by itself to setup config files and folder |
33 | | - for irs and download the ffmpeg binaries |
34 | | - -a ARTIST, --artist ARTIST |
35 | | - Specify artist name. Must be used with -s/--song or |
36 | | - -A/--album |
37 | | - -s SONG, --song SONG Specify song name. Must be used with -a/--artist |
38 | | - -A ALBUM, --album ALBUM |
39 | | - Specify album name. Can be used by itself. |
40 | | - -p PLAYLIST, --playlist PLAYLIST |
41 | | - Specify playlist name. Must be used with -A/--album |
42 | | - -u USERNAME, --username USERNAME |
43 | | - Specify user name for playlist. Must be used with |
44 | | - -A/--album |
45 | | - -o ORGANIZATION, --organization ORGANIZATION |
46 | | - Specify type of organization for list. Used when |
47 | | - downloading spotify playlist/album |
48 | | -``` |
49 | 37 |
|
50 | | -So all of these are valid commands: |
51 | | -``` |
52 | | -$ irs -a "Brandon Flowers" -s "Lonely Town" |
53 | | -$ irs -u "spotify" -p "Brain Food" |
54 | | -$ irs -A "Suicide Squad: The Album" |
55 | | -``` |
56 | | -But these are not: |
| 38 | +## Usage |
| 39 | + |
57 | 40 | ``` |
58 | | -$ irs -s "Bohemian Rhapsody" |
59 | | -$ irs -p "Best Nirvana" |
| 41 | +~ $ irs -h |
| 42 | +
|
| 43 | +Usage: irs [--help] [--version] [--install] |
| 44 | + [-s <song> -a <artist>] |
| 45 | + [-A <album> -a <artist>] |
| 46 | + [-p <playlist> -a <username>] |
| 47 | +
|
| 48 | +Arguments: |
| 49 | + -h, --help Show this help message and exit |
| 50 | + -v, --version Show the program version and exit |
| 51 | + -i, --install Download binaries to config location |
| 52 | + -c, --config Show config file location |
| 53 | + -a, --artist <artist> Specify artist name for downloading |
| 54 | + -s, --song <song> Specify song name to download |
| 55 | + -A, --album <album> Specify the album name to download |
| 56 | + -p, --playlist <playlist> Specify the playlist name to download |
| 57 | +
|
| 58 | +Examples: |
| 59 | + $ irs --song "Bohemian Rhapsody" --artist "Queen" |
| 60 | + # => downloads the song "Bohemian Rhapsody" by "Queen" |
| 61 | + $ irs --album "Demon Days" --artist "Gorillaz" |
| 62 | + # => downloads the album "Demon Days" by "Gorillaz" |
| 63 | + $ irs --playlist "a different drummer" --artist "prakkillian" |
| 64 | + # => downloads the playlist "a different drummer" by the user prakkillian |
60 | 65 | ``` |
61 | 66 |
|
62 | | -## Spotify Tokens |
63 | | - |
64 | | -To download metadata through spotify, you'll want to head to their Dev Apps page, [here](https://developer.spotify.com/my-applications/). After doing that you'll want to create a new app. Name it whatever you want and then once you've done that, find the `Client ID` and `Client Secret` keys. You'll want to take those keys and paste them into your system's environment variables as `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`, correspondingly. Voilà! You can now download metadata with IRS! |
65 | | - |
66 | | -## Metadata |
67 | | - |
68 | | -Currently, the program attaches the following metadata to the downloaded files: |
69 | | - - Title |
70 | | - - Artist |
71 | | - - Album |
72 | | - - Album Art |
73 | | - - Genre |
74 | | - - Track Number |
75 | | - - Disc Number |
76 | | - |
77 | | -## Wishlist |
78 | | - |
79 | | - - [x] Full album downloading |
80 | | - - [x] Album art metadata correctly displayed |
81 | | - - [x] Spotify playlist downloading |
82 | | - - [ ] Comment metadata |
83 | | - - [ ] Compilation metadata |
84 | | - - [ ] GUI/Console interactive version - *in progress* |
85 | | - - [ ] Lyric metadata |
| 67 | +### Demo |
| 68 | + |
| 69 | +[](https://asciinema.org/a/332793) |
| 70 | + |
| 71 | +## Installation |
| 72 | + |
| 73 | +### Pre-built |
| 74 | + |
| 75 | +Just download the latest release for your platform |
| 76 | +[here](https://github.com/cooperhammond/irs/releases). |
| 77 | + |
| 78 | +### From Source |
| 79 | + |
| 80 | +If you're one of those cool people who compiles from source |
| 81 | + |
| 82 | +1. Install crystal-lang |
| 83 | + ([`https://crystal-lang.org/install/`](https://crystal-lang.org/install/)) |
| 84 | +1. Clone it (`git clone https://github.com/cooperhammond/irs`) |
| 85 | +1. CD it (`cd irs`) |
| 86 | +1. Build it (`shards build`) |
| 87 | + |
| 88 | +### Setup |
| 89 | + |
| 90 | +1. Create a `.yaml` config file somewhere on your system (usually `~/.irs/`) |
| 91 | +1. Copy the following into it |
| 92 | + ```yaml |
| 93 | + binary_directory: ~/.irs/bin |
| 94 | + music_directory: ~/Music |
| 95 | + client_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| 96 | + client_secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| 97 | + single_folder_playlist: |
| 98 | + enabled: true |
| 99 | + retain_playlist_order: true |
| 100 | + unify_into_album: false |
| 101 | + ``` |
| 102 | +1. Set the environment variable `IRS_CONFIG_LOCATION` pointing to that file |
| 103 | +1. Go to [`https://developer.spotify.com/dashboard/`](https://developer.spotify.com/dashboard/) |
| 104 | +1. Log in or create an account |
| 105 | +1. Click `CREATE A CLIENT ID` |
| 106 | +1. Enter all necessary info, true or false, continue |
| 107 | +1. Find your client key and client secret |
| 108 | +1. Copy each respectively into the X's in your config file |
| 109 | +1. Run `irs --install` and answer the prompts! |
| 110 | + |
| 111 | +You should be good to go! Run the file from your command line to get more help on |
| 112 | +usage or keep reading! |
| 113 | + |
| 114 | +# Config |
| 115 | + |
| 116 | +You may have noticed that there's a config file with more than a few options. |
| 117 | +Here's what they do: |
| 118 | +```yaml |
| 119 | +binary_directory: ~/.irs/bin |
| 120 | +music_directory: ~/Music |
| 121 | +client_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| 122 | +client_secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| 123 | +single_folder_playlist: |
| 124 | + enabled: true |
| 125 | + retain_playlist_order: true |
| 126 | + unify_into_album: false |
| 127 | +``` |
| 128 | + - `binary_directory`: a path specifying where the downloaded binaries should |
| 129 | + be placed |
| 130 | + - `music_directory`: a path specifying where downloaded mp3s should be placed. |
| 131 | + Note that there will be more structure created inside that folder, usually |
| 132 | + in the format of `music-dir>artist-name>album-name>track` |
| 133 | + - `client_key`: a client key from your spotify API application |
| 134 | + - `client_secret`: a client secret key from your spotify API application |
| 135 | + - `single_folder_playlist/enabled`: if set to true, all mp3s from a downloaded |
| 136 | + playlist will be placed in the same folder. |
| 137 | + - `single_folder_playlist/retain_playlist_order`: if set to true, the track |
| 138 | + numbers of the mp3s of the playlist will be overwritten to correspond to |
| 139 | + their place in the playlist |
| 140 | + - `single_folder_playlist/unify_into_album`: if set to true, will overwrite |
| 141 | + the album name and album image of the mp3 with the title of your playlist |
| 142 | + and the image for your playlist respectively |
| 143 | + |
| 144 | +## How it works |
| 145 | + |
| 146 | +**At it's core** `irs` downloads individual songs. It does this by interfacing |
| 147 | +with the Spotify API, grabbing metadata, and then searching Youtube for a video |
| 148 | +containing the song's audio. It will download the video using |
| 149 | +[`youtube-dl`](https://github.com/ytdl-org/youtube-dl), extract the audio using |
| 150 | +[`ffmpeg`](https://ffmpeg.org/), and then pack the audio and metadata together |
| 151 | +into an MP3. |
| 152 | + |
| 153 | +From the core, it has been extended to download the index of albums and |
| 154 | +playlists through the spotify API, and then iteratively use the method above |
| 155 | +for downloading each song. |
| 156 | + |
| 157 | +It used to be in python, but |
| 158 | +1. I wasn't a fan of python's limited ability to distribute standalone binaries |
| 159 | +1. It was a charlie foxtrot of code that I made when I was little and I wanted |
| 160 | + to refine it |
| 161 | +1. `crystal-lang` made some promises and I was interested in seeing how well it |
| 162 | + did (verdict: if you're building high-level tools you want to run quickly |
| 163 | + and distribute, it's perfect) |
| 164 | + |
| 165 | + |
| 166 | +## Contributing |
| 167 | + |
| 168 | +Any and all contributions are welcome. If you think of a cool feature, send a |
| 169 | +PR or shoot me an [email](mailto:[email protected]). If you think something |
| 170 | +could be implemented better, _please_ shoot me an email. If you like what I'm |
| 171 | +doing here, _pretty please_ shoot me an email. |
| 172 | + |
| 173 | +1. Fork it (<https://github.com/your-github-user/irs/fork>) |
| 174 | +2. Create your feature branch (`git checkout -b my-new-feature`) |
| 175 | +3. Commit your changes (`git commit -am 'Add some feature'`) |
| 176 | +4. Push to the branch (`git push origin my-new-feature`) |
| 177 | +5. Create a new Pull Request |
0 commit comments