mirror of
https://github.com/cooperhammond/irs.git
synced 2025-01-17 21:17:07 +00:00
README updata, it's pretty AND useful now
This commit is contained in:
Cooper Hammond
parent
5f8acac053
commit
dd23fb5527
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -7,6 +7,7 @@
|
||||||
*.dwarf
|
*.dwarf
|
||||||
|
|
||||||
*.mp3
|
*.mp3
|
||||||
|
*.webm*
|
||||||
.ripper.log
|
.ripper.log
|
||||||
ffmpeg
|
ffmpeg
|
||||||
ffprobe
|
ffprobe
|
||||||
|
|
|
||||||
161
README.md
161
README.md
|
|
@ -1,16 +1,93 @@
|
||||||
# `irs`
|
# irs: The Ironic Repositioning System
|
||||||
###### AKA `Ironic Repositioning System`
|
|
||||||
|
|
||||||
[](https://crystal-lang.org/)
|
[](https://crystal-lang.org/)
|
||||||
[](https://github.com/cooperhammond/irs/blob/master/LICENSE)
|
[](https://github.com/cooperhammond/irs/blob/master/LICENSE)
|
||||||
[](https://saythanks.io/to/kepoorhampond)
|
[](https://saythanks.io/to/kepoorh%40gmail.com)
|
||||||
|
|
||||||
> A music scraper that understands your metadata needs.
|
> A music scraper that understands your metadata needs.
|
||||||
|
|
||||||
|
`irs` is a command-line application that downloads audio and metadata in order
|
||||||
|
to package an mp3 with both. Extensible, the user can download individual
|
||||||
|
songs, entire albums, or playlists from Spotify.
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<img src="https://i.imgur.com/7QTM6rD.png" height="400" title="#1F816D" />
|
||||||
|
</p>
|
||||||
|
<p align="center"
|
||||||
|
|
||||||
|
[](https://forthebadge.com)
|
||||||
|
[](https://forthebadge.com)
|
||||||
|
[](https://forthebadge.com)
|
||||||
|
</p>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Usage](#usage)
|
||||||
|
- [Demo](#demo)
|
||||||
|
- [Installation](#installation)
|
||||||
|
- [Pre-built](#pre-built)
|
||||||
|
- [From source](#from-source)
|
||||||
|
- [Set up](#setup)
|
||||||
|
- [Config](#config)
|
||||||
|
- [How it works](#how-it-works)
|
||||||
|
- [Contributing](#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
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
[](https://asciinema.org/a/332793)
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
1. Download the latest release for your platform [here](https://github.com/cooperhammond/irs/releases)
|
### Pre-built
|
||||||
1. Create a `.yaml` config file somewhere on your system
|
|
||||||
|
Just download the latest release for your platform
|
||||||
|
[here](https://github.com/cooperhammond/irs/releases).
|
||||||
|
|
||||||
|
### From Source
|
||||||
|
|
||||||
|
If you're one of those cool people who compiles from source
|
||||||
|
|
||||||
|
1. Install crystal-lang
|
||||||
|
([`https://crystal-lang.org/install/`](https://crystal-lang.org/install/))
|
||||||
|
1. Clone it (`git clone https://github.com/cooperhammond/irs`)
|
||||||
|
1. CD it (`cd irs`)
|
||||||
|
1. Build it (`shards build`)
|
||||||
|
|
||||||
|
### Setup
|
||||||
|
|
||||||
|
1. Create a `.yaml` config file somewhere on your system (usually `~/.irs/`)
|
||||||
1. Copy the following into it
|
1. Copy the following into it
|
||||||
```yaml
|
```yaml
|
||||||
binary_directory: ~/.irs/bin
|
binary_directory: ~/.irs/bin
|
||||||
|
|
@ -20,7 +97,7 @@
|
||||||
single_folder_playlist:
|
single_folder_playlist:
|
||||||
enabled: true
|
enabled: true
|
||||||
retain_playlist_order: true
|
retain_playlist_order: true
|
||||||
overwrite_album: false
|
unify_into_album: false
|
||||||
```
|
```
|
||||||
1. Set the environment variable `IRS_CONFIG_LOCATION` pointing to that file
|
1. Set the environment variable `IRS_CONFIG_LOCATION` pointing to that file
|
||||||
1. Go to [`https://developer.spotify.com/dashboard/`](https://developer.spotify.com/dashboard/)
|
1. Go to [`https://developer.spotify.com/dashboard/`](https://developer.spotify.com/dashboard/)
|
||||||
|
|
@ -28,40 +105,70 @@
|
||||||
1. Click `CREATE A CLIENT ID`
|
1. Click `CREATE A CLIENT ID`
|
||||||
1. Enter all necessary info, true or false, continue
|
1. Enter all necessary info, true or false, continue
|
||||||
1. Find your client key and client secret
|
1. Find your client key and client secret
|
||||||
2. Copy them into where all the X's are in your config file from above
|
1. Copy each respectively into the X's in your config file
|
||||||
|
1. Run `irs --install` and answer the prompts!
|
||||||
|
|
||||||
You should be good to go! Run the file from your command line to get help on usage or keep reading!
|
You should be good to go! Run the file from your command line to get more help on
|
||||||
|
usage or keep reading!
|
||||||
|
|
||||||
##### Optionally From Source
|
# Config
|
||||||
|
|
||||||
Or if you're one of those cool people who compiles from source
|
You may have noticed that there's a config file with more than a few options.
|
||||||
|
Here's what they do:
|
||||||
1. Install crystal-lang ([`https://crystal-lang.org/install/`](https://crystal-lang.org/install/))
|
```yaml
|
||||||
1. Clone it (`git clone https://github.com/cooperhammond/irs`)
|
binary_directory: ~/.irs/bin
|
||||||
1. CD it (`cd irs`)
|
music_directory: ~/Music
|
||||||
1. Build it (`shards build`)
|
client_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||||||
|
client_secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||||||
## Usage
|
single_folder_playlist:
|
||||||
|
enabled: true
|
||||||
<p align="center">
|
retain_playlist_order: true
|
||||||
<img src="https://i.imgur.com/uYKh101.png" height="600" />
|
unify_into_album: false
|
||||||
</p>
|
```
|
||||||
|
- `binary_directory`: a path specifying where the downloaded binaries should
|
||||||
|
be placed
|
||||||
|
- `music_directory`: a path specifying where downloaded mp3s should be placed.
|
||||||
|
Note that there will be more structure created inside that folder, usually
|
||||||
|
in the format of `music-dir>artist-name>album-name>track`
|
||||||
|
- `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 downloaded
|
||||||
|
playlist will be placed in the same folder.
|
||||||
|
- `single_folder_playlist/retain_playlist_order`: if set to true, the track
|
||||||
|
numbers of the mp3s of the playlist will be overwritten to correspond to
|
||||||
|
their place in the playlist
|
||||||
|
- `single_folder_playlist/unify_into_album`: if set to true, will overwrite
|
||||||
|
the album name and album image of the mp3 with the title of your playlist
|
||||||
|
and the image for your playlist respectively
|
||||||
|
|
||||||
## How it works
|
## How it works
|
||||||
|
|
||||||
**At it's core** `irs` downloads individual songs. It does this by interfacing with the Spotify API, grabbing metadata, and then searching Youtube for a video containing the song's audio. It will download the video using [`youtube-dl`](https://github.com/ytdl-org/youtube-dl), extract the audio using [`ffmpeg`](https://ffmpeg.org/), and then pack the audio and metadata together into an MP3.
|
**At it's core** `irs` downloads individual songs. It does this by interfacing
|
||||||
|
with the Spotify API, grabbing metadata, and then searching Youtube for a video
|
||||||
|
containing the song's audio. It will download the video using
|
||||||
|
[`youtube-dl`](https://github.com/ytdl-org/youtube-dl), extract the audio using
|
||||||
|
[`ffmpeg`](https://ffmpeg.org/), and then pack the audio and metadata together
|
||||||
|
into an MP3.
|
||||||
|
|
||||||
From the core, it has been extended to download the index of albums and playlists through the spotify API, and then iteratively use the method above for downloading each song.
|
From the core, it has been extended to download the index of albums and
|
||||||
|
playlists through the spotify API, and then iteratively use the method above
|
||||||
|
for downloading each song.
|
||||||
|
|
||||||
It used to be in `python`, but
|
It used to be in python, but
|
||||||
1. I wasn't a fan of python's limited ability to distribute standalone binaries
|
1. I wasn't a fan of python's limited ability to distribute standalone binaries
|
||||||
1. It was a clusterfuck of code that I made when I was little and I wanted to refine it
|
1. It was a charlie foxtrot of code that I made when I was little and I wanted
|
||||||
2. `crystal-lang` made some promises and I was interested in seeing how well it did (verdict: if you're building high-level tools you want to run quickly and distribute, it's a joy to work in)
|
to refine it
|
||||||
|
1. `crystal-lang` made some promises and I was interested in seeing how well it
|
||||||
|
did (verdict: if you're building high-level tools you want to run quickly
|
||||||
|
and distribute, it's perfect)
|
||||||
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Any and all contributions are welcome. If you think of a cool feature, send a PR or shoot me an [email](mailto:kepoorh@gmail.com). If you think something could be implemented better, _please_ shoot me an email. If you like what I'm doing here, _pretty please_ shoot me an email.
|
Any and all contributions are welcome. If you think of a cool feature, send a
|
||||||
|
PR or shoot me an [email](mailto:kepoorh@gmail.com). If you think something
|
||||||
|
could be implemented better, _please_ shoot me an email. If you like what I'm
|
||||||
|
doing here, _pretty please_ shoot me an email.
|
||||||
|
|
||||||
1. Fork it (<https://github.com/your-github-user/irs/fork>)
|
1. Fork it (<https://github.com/your-github-user/irs/fork>)
|
||||||
2. Create your feature branch (`git checkout -b my-new-feature`)
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue