mirror of
https://github.com/cooperhammond/irs.git
synced 2024-12-21 17:25:28 +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
|
||||
|
||||
*.mp3
|
||||
*.webm*
|
||||
.ripper.log
|
||||
ffmpeg
|
||||
ffprobe
|
||||
|
|
|
|||
161
README.md
161
README.md
|
|
@ -1,16 +1,93 @@
|
|||
# `irs`
|
||||
###### AKA `Ironic Repositioning System`
|
||||
# irs: The Ironic Repositioning System
|
||||
|
||||
[](https://crystal-lang.org/)
|
||||
[](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.
|
||||
|
||||
`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
|
||||
|
||||
1. Download the latest release for your platform [here](https://github.com/cooperhammond/irs/releases)
|
||||
1. Create a `.yaml` config file somewhere on your system
|
||||
### Pre-built
|
||||
|
||||
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
|
||||
```yaml
|
||||
binary_directory: ~/.irs/bin
|
||||
|
|
@ -20,7 +97,7 @@
|
|||
single_folder_playlist:
|
||||
enabled: 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. Go to [`https://developer.spotify.com/dashboard/`](https://developer.spotify.com/dashboard/)
|
||||
|
|
@ -28,40 +105,70 @@
|
|||
1. Click `CREATE A CLIENT ID`
|
||||
1. Enter all necessary info, true or false, continue
|
||||
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
|
||||
|
||||
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`)
|
||||
|
||||
## Usage
|
||||
|
||||
<p align="center">
|
||||
<img src="https://i.imgur.com/uYKh101.png" height="600" />
|
||||
</p>
|
||||
You may have noticed that there's a config file with more than a few options.
|
||||
Here's what they do:
|
||||
```yaml
|
||||
binary_directory: ~/.irs/bin
|
||||
music_directory: ~/Music
|
||||
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 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
|
||||
|
||||
**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. It was a clusterfuck of code that I made when I was little and I wanted to refine it
|
||||
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)
|
||||
1. It was a charlie foxtrot of code that I made when I was little and I wanted
|
||||
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
|
||||
|
||||
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>)
|
||||
2. Create your feature branch (`git checkout -b my-new-feature`)
|
||||
|
|
|
|||
Loading…
Reference in a new issue