irs: The Ironic Repositioning System

A music scraper that understands your metadata needs.

irs is a command-line application that downloads audio and metadata in orderto package an mp3 with both. Extensible, the user can download individualsongs, entire albums, or playlists from Spotify.

Table of Contents

• Usage
  • Demo
• Installation
  • Pre-built
  • From source
  • Set up
• Config
• How it works
• Contributing

Usage

~ $ irs -h

Usage: irs [--help] [--version] [--install]
           [-s <song> -a <artist>]
           [-A <album> -a <artist>]
           [-p <playlist> -a <username>]

Arguments:
    -h, --help                  Show this help message and exit
    -v, --version               Show the program version and exit
    -i, --install               Download binaries to config location
    -c, --config                Show config file location
    -a, --artist <artist>       Specify artist name for downloading
    -s, --song <song>           Specify song name to download
    -A, --album <album>         Specify the album name to download
    -p, --playlist <playlist>   Specify the playlist name to download
    -u, --url <url>             Specify the youtube url to download from (for single songs only)
    -g, --give-url              Specify the youtube url sources while downloading (for albums or playlists only only)

Examples:
    $ irs --song "Bohemian Rhapsody" --artist "Queen"
    # => downloads the song "Bohemian Rhapsody" by "Queen"
    $ irs --album "Demon Days" --artist "Gorillaz"
    # => downloads the album "Demon Days" by "Gorillaz"
    $ irs --playlist "a different drummer" --artist "prakkillian"
    # => downloads the playlist "a different drummer" by the user prakkillian

Demo

Installation

Pre-built

Just download the latest release for your platformhere.

Note that the binaries right now have only been tested on WSL. They should run on most linux distros, and OS X, but if they don't please make an issue above.

From Source

If you're one of those cool people who compiles from source

1. Install crystal-lang(https://crystal-lang.org/install/)
2. Clone it (git clone https://github.com/cooperhammond/irs)
3. CD it (cd irs)
4. Build it (shards build)

Setup

1. Create a .yaml config file somewhere on your system (usually ~/.irs/)
2. Copy the following into it

   binary_directory: ~/.irs/bin
   music_directory: ~/Music
   filename_pattern: "{track_number} - {title}"
   directory_pattern: "{artist}/{album}"
   client_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   client_secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   single_folder_playlist:
       enabled: true
       retain_playlist_order: true
       unify_into_album: false

3. Set the environment variable IRS_CONFIG_LOCATION pointing to that file
4. Go to https://developer.spotify.com/dashboard/
5. Log in or create an account
6. Click CREATE A CLIENT ID
7. Enter all necessary info, true or false, continue
8. Find your client key and client secret
9. Copy each respectively into the X's in your config file
10. Run irs --install and answer the prompts!

You should be good to go! Run the file from your command line to get more help onusage or keep reading!

Config

You may have noticed that there's a config file with more than a few options.Here's what they do:

binary_directory: ~/.irs/bin
music_directory: ~/Music
filename_pattern: "{track_number} - {title}"
directory_pattern: "{artist}/{album}"
client_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
client_secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
single_folder_playlist:
    enabled: true
    retain_playlist_order: true
    unify_into_album: false

• binary_directory: a path specifying where the downloaded binaries shouldbe placed
• music_directory: a path specifying where downloaded mp3s should be placed.
• filename_pattern: a pattern for the output filename of the mp3
• directory_pattern: a pattern for the folder structure your mp3s are saved in
• client_key: a client key from your spotify API application
• client_secret: a client secret key from your spotify API application
• single_folder_playlist/enabled: if set to true, all mp3s from a downloadedplaylist will be placed in the same folder.
• single_folder_playlist/retain_playlist_order: if set to true, the tracknumbers of the mp3s of the playlist will be overwritten to correspond totheir place in the playlist
• single_folder_playlist/unify_into_album: if set to true, will overwritethe album name and album image of the mp3 with the title of your playlistand the image for your playlist respectively

In a pattern following keywords will be replaced:

Beware OS-restrictions when naming your mp3s.

Pattern Examples:

music_directory: ~/Music
filename_pattern: "{track_number} - {title}"
directory_pattern: "{artist}/{album}"

Outputs: ~/Music/Queen/Stone Cold Classics/9 - Bohemian Rhapsody.mp3

music_directory: ~/Music
filename_pattern: "{artist} - {title}"
directory_pattern: ""

Outputs: ~/Music/Queen - Bohemian Rhapsody.mp3

music_directory: ~/Music
filename_pattern: "{track_number} of {total_tracks} - {title}"
directory_pattern: "{year}/{artist}/{album}"

Outputs: ~/Music/2006/Queen/Stone Cold Classics/9 of 14 - Bohemian Rhapsody.mp3

music_directory: ~/Music
filename_pattern: "{track_number}. {title}"
directory_pattern: "irs/{artist} - {album}"

Outputs: ~/Music/irs/Queen - Stone Cold Classics/9. Bohemian Rhapsody.mp3

How it works

At it's core irs downloads individual songs. It does this by interfacingwith the Spotify API, grabbing metadata, and then searching Youtube for a videocontaining the song's audio. It will download the video usingyoutube-dl, extract the audio usingffmpeg, and then pack the audio and metadata togetherinto an MP3.

From the core, it has been extended to download the index of albums andplaylists through the spotify API, and then iteratively use the method abovefor downloading each song.

It used to be in python, but

1. I wasn't a fan of python's limited ability to distribute standalone binaries
2. It was a charlie foxtrot of code that I made when I was little and I wantedto refine it
3. crystal-lang made some promises and I was interested in seeing how well itdid (verdict: if you're building high-level tools you want to run quicklyand distribute, it's perfect)

Contributing

Any and all contributions are welcome. If you think of a cool feature, send aPR or shoot me an email. If you think somethingcould be implemented better, please shoot me an email. If you like what I'mdoing here, pretty please shoot me an email.

1. Fork it (https://github.com/your-github-user/irs/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request