freyrcli/freyrjs

By freyrcli

•Updated over 2 years ago

Versatile Multi-Service Music Downloader with NodeJS

Image

10K+

Overview Tags

freyrcli/freyrjs repository overview

⁠ ⁠
FreyrJS

⁠ A versatile, service-agnostic music downloader and manager

⁠

_{Built with ❤︎ by
Miraculous Owonubi⁠}

⁠Demo

⁠Support the project

⁠Donate via

⁠Crypto

Via Coinbase (BTC, ETH, USDC, LTC, DAI, BCH):
- Support us with $5⁠ | $10⁠ | $15⁠ | $20⁠
- Donate anything you want⁠
Or Directly:
- : bc1qqe5y9kw7ewne8njdces8e4ajx5u7zhfftdvl33
- : GB6GPPXXJTQ6EFYQQ4PFA4WEAT5G2DIDILOEDLYH76743UUVDDU4KOWY
- : zs10awcwm4uwpjr3mxxdwe03fda0j0zn95s4hu3qxlvhfajjw8es98ftmpaava7zh735x9s22pan0l

⁠Installation

⁠Manually

Ensure all requirements⁠ are satisfied before installing.

You can use either of these options to install freyr:

Install globally via NPM⁠:
```
npm install -g miraclx/freyr-js
```
Install globally via Yarn⁠:
```
yarn global add miraclx/freyr-js
```

Or alternatively, you can build from source

git clone https://github.com/miraclx/freyr-js.git freyr-js
cd freyr-js

If using npm:

npm install

# to have access to the freyr command globally
npm link

If using yarn:

yarn install

# to have access to the freyr command globally
yarn link

⁠Docker

We provide officially prebuilt images⁠ (automated builds from this repo).

Pull the image:

docker pull freyrcli/freyrjs

Base Image	Size	Tag
Alpine (musl) *		`freyrcli/freyrjs:latest`
Arch Linux		`freyrcli/freyrjs:archlinux`

*: default

⁠Usage (Docker)

Structure

docker run -it --rm -v $PWD:/data <tag> [options, arguments and queries...]

Example, with the freyrcli/freyrjs:latest tag:

docker run -it --rm -v $PWD:/data freyrcli/freyrjs:latest

Alternatively, create a handy alias

alias freyr='docker run -it --rm -v $PWD:/data freyrcli/freyrjs:latest'

[See Docker Development⁠]

⁠Getting Started

⁠Requirements

As an alternative to setting up freyr and its dependencies on your host system, consider the Docker installation method⁠ for a containerized experience.

python >= v3.2

Download for your individual platforms here https://www.python.org/downloads/⁠

Linux: (check individual package managers)

* Debian: sudo apt-get install python3.6
* Arch Linux: sudo pacman -S python
Android (Termux): apt install python
Alpine Linux: sudo apk add python3
(*: should already be preinstalled)

nodejs >= v12.0.0

Download for your individual platforms here https://nodejs.org/en/download/⁠

macOS + Linux: nvm⁠ recommended.

# install node with this nvm command
# freyr works with a minimum of v12
$ nvm install --lts

Android (Termux): apt install nodejs
Alpine Linux: sudo apk add nodejs

ffmpeg >= v0.9

Download for your individual platforms here https://ffmpeg.org/download.html⁠

Windows + macOS:
- Ensure to extract the ffmpeg binary from the compressed file, if it's in one.
- make sure it's available in your PATH
- otherwise, set FFMPEG_PATH to explicitly specify binary to use
Linux: (check individual package managers)
- Debian: The ppa:mc3man/trusty-media PPA provides recent builds
- Arch Linux: sudo pacman -S ffmpeg
- Android (Termux): apt install ffmpeg
- Alpine Linux: sudo apk add ffmpeg

youtube-dl @ latest

automatically fetched by installing this package
optionally, you can fetch the source yourself https://github.com/ytdl-org/youtube-dl⁠ and include in your PATH

AtomicParsley >= (v0.9.6 | 20200701)

First, download the latest release for your individual platforms here https://github.com/wez/atomicparsley/releases/latest⁠

Then;

Windows:
- unzip and place the AtomicParsley.exe in your PATH.
- or the bins/windows folder of this project directory. Create the folder(s) if they don't exist.
Linux + macOS (the brew package isn't recommended):
- unzip and place the AtomicParsley in your PATH.
- or the bins/posix folder of this project directory. Create the folder(s) if they don't exist.
Alternatively:
- Debian: sudo apt-get install atomicparsley
- Arch Linux: sudo pacman -S atomicparsley
- Android (Termux): apt install atomicparsley
- Build from source: See wez/AtomicParsley⁠

⁠Usage

Usage: freyr [options] [query...]
Usage: freyr [options] [subcommand]

[See Service Support⁠].

⁠Show freyr help and list subcommands

freyr --help

⁠Get CLI Help

*The get subcommand is implicit and default.

Usage: freyr [options] get [options] [query...]
Usage: freyr [options] [query...]

freyr get --help

    ____
   / __/_______  __  _______
  / /_/ ___/ _ \/ / / / ___/
 / __/ /  /  __/ /_/ / /
/_/ /_/   \___/\__, /_/
              /____/ v0.1.0

freyr v0.1.0 - (c) Miraculous Owonubi <[email protected]>
-------------------------------------------------------------
Usage: freyr get [options] [query...]

Download music tracks from queries

Options:
  -i, --input <FILE>           use URIs found in the specified FILE as queries (file size limit: 1 MiB)
                               (each query on a new line, use '#' for comments, whitespaces ignored)
                               (example: `-i queue.txt`)
  -b, --bitrate <N>            set audio quality / bitrate for audio encoding
                               (valid: 96,128,160,192,256,320) (default: "320k")
  -n, --chunks <N>             number of concurrent chunk streams with which to download (default: 7)
  -r, --retries <N>            set number of retries for each chunk before giving up
                               (`infinite` for infinite) (default: 10)
  -t, --meta-retries <N>       set number of retries for collating track feeds (`infinite` for infinite) (default: 5)
  -d, --directory <DIR>        save tracks to DIR/..
  -c, --cover <NAME>           custom name for the cover art (default: "cover.png")
  --cover-size <SIZE>          preferred cover art dimensions
                               (format: <width>x<height> or <size> as <size>x<size>) (default: "640x640")
  -C, --no-cover               skip saving a cover art
  -x, --format <FORMAT>        preferred audio output format (to export) (unimplemented)
                               (valid: mp3,m4a,flac) (default: "m4a")
  -D, --downloader <SERVICE>   specify a preferred download source or a `,`-separated preference order
                               (valid: youtube,yt_music) (default: "yt_music")
  -l, --filter <MATCH>         filter matches off patterns (repeatable and optionally `,`-separated)
                               (value omission implies `true` if applicable)
                               (format: <key=value>) (example: title="when we all fall asleep*",type=album)
                               See `freyr help filter` for more information
  -L, --filter-case            enable case sensitivity for glob matches on the filters
  -z, --concurrency <SPEC>     key-value concurrency pairs (repeatable and optionally `,`-separated)
                               (format: <[key=]value>) (key omission implies track concurrency)
                               (valid(key): queries,tracks,trackStage,downloader,encoder,embedder)
                               (example: `queries=2,downloader=4` processes 2 CLI queries,
                               downloads at most 4 tracks concurrently)
  --gapless                    set the gapless playback flag for all tracks
  -f, --force                  force overwrite of existing files
  -o, --config <FILE>          specify alternative configuration file
  -p, --playlist <FILENAME>    create playlist for all successfully collated tracks
  -P, --no-playlist            skip creating a playlist file for collections
  --playlist-dir <DIR>         directory to save playlist file to, if any, (default: tracks base directory)
  --playlist-noappend          do not append to the playlist file, if any exists
  --playlist-noescape          do not escape invalid characters within playlist entries
  --playlist-namespace <SPEC>  namespace to prefix on each track entry, relative to tracks base directory
                               useful for, but not limited to custom (file:// or http://) entries
                               (example, you can prefix with a HTTP domain path: `http://webpage.com/music`)
  --playlist-force-append      force append collection tracks to the playlist file
  -s, --storefront <COUNTRY>   country storefront code (example: us,uk,ru)
  -T, --no-tree                don't organise tracks in directory structure `[DIR/]<ARTIST>/<ALBUM>/<TRACK>`
  --tags                       tag configuration specification (repeatable and optionally `,`-separated) (unimplemented)
                               (format: <key=value>) (reserved keys: [exclude, account])
  --via-tor                    tunnel network traffic through the tor network (unimplemented)
  --cache-dir <DIR>            specify alternative cache directory, `<tmp>` for tempdir
  -m, --mem-cache <SIZE>       max size of bytes to be cached in-memory for each download chunk
  --no-mem-cache               disable in-memory chunk caching (restricts to sequential download)
  --timeout <N>                network inactivity timeout (ms) (default: 10000)
  --no-auth                    skip authentication procedure
  --no-browser                 disable auto-launching of user browser
  --no-net-check               disable internet connection check
  --ffmpeg <PATH>              explicit path to the ffmpeg binary
  --youtube-dl <PATH>          explicit path to the youtube-dl binary
  --atomic-parsley <PATH>      explicit path to the atomic-parsley binary
  --no-stats                   don't show the stats on completion
  --pulsate-bar                show a pulsating bar
  --single-bar                 show a single bar for the download, hide chunk-view
                               (default when number of chunks/segments exceed printable space)
  -h, --help                   show this help information

Environment Variables:
  SHOW_DEBUG_STACK             show extended debug information
  FFMPEG_PATH                  custom ffmpeg path, alternatively use `--ffmpeg`
  YOUTUBE_DL_PATH              custom youtube-dl path, alternatively use `--youtube-dl`
  ATOMIC_PARSLEY_PATH          custom AtomicParsley path, alternatively use `--atomic-parsley`

Info:
  When downloading playlists, the tracks are downloaded individually into
  their respective folders. However, a m3u8 playlist file is generated in
  the base directory with the name of the playlist that lists the tracks

⁠Download a Spotify track

freyr spotify:track:5FNS5Vj69AhRGJWjhrAd01

    ____
   / __/_______  __  _______
  / /_/ ___/ _ \/ / / / ___/
 / __/ /  /  __/ /_/ / /
/_/ /_/   \___/\__, /_/
              /____/ v0.1.0

freyr v0.1.0 - (c) Miraculous Owonubi <[email protected]>
-------------------------------------------------------------
Checking directory permissions...[done]
[spotify:track:5FNS5Vj69AhRGJWjhrAd01]
 [•] Identifying service...[Spotify]
 [•] Checking authentication...[unauthenticated]
 [Spotify Login]
  [•] Logging in...[done]
 Detected [track]
 Obtaining track metadata...[done]
  ➤ Title: Slow Dance
  ➤ Album: Slow Dance
  ➤ Artist: AJ Mitchell
  ➤ Year: 2019
  ➤ Playtime: 02:58
 [•] Collating...
 • [01 Slow Dance]
    | ➤ Collating sources...
    |  ➤ [•] YouTube Music...[success, found 1 source]
    | ➤ Awaiting audiofeeds...[done]
    | [✓] Got album art
    | [✓] Got raw track file
    | [•] Post Processing...
 [•] Download Complete
 [•] Embedding Metadata...
  • [✓] 01 Slow Dance
[•] Collation Complete
========== Stats ==========
 [•] Runtime: [31.7s]
 [•] Total queries: [01]
 [•] Total tracks: [01]
     » Skipped: [00]
     ✓ Passed:  [01]
     ✕ Failed:  [00]
 [•] Output directory: [.]
 [•] Cover Art: cover.png (640x640)
 [•] Total Output size: 7.30 MB
 [•] Total Network Usage: 3.12 MB
     ♫ Media: 3.02 MB
     ➤ Album Art: 106.76 KB
 [•] Output bitrate: 320k
===========================

⁠Download an Apple Music album

freyr https://music.apple.com/us/album/im-sorry-im-not-sorry-ep/1491795443

    ____
   / __/_______  __  _______
  / /_/ ___/ _ \/ / / / ___/
 / __/ /  /  __/ /_/ / /
/_/ /_/   \___/\__, /_/
              /____/ v0.1.0

freyr v0.1.0 - (c) Miraculous Owonubi <[email protected]>
-------------------------------------------------------------
Checking directory permissions...[done]
[https://music.apple.com/us/album/im-sorry-im-not-sorry-ep/1491795443]
 [•] Identifying service...[Apple Music]
 [•] Checking authentication...[authenticated]
 Detected [album]
 Obtaining album metadata...[done]
  ➤ Album Name: I'm Sorry, I'm Not Sorry
  ➤ Artist: Sody
  ➤ Tracks: 4
  ➤ Type: Album
  ➤ Year: 2020
  ➤ Genres: Singer/Songwriter, Music
 [•] Collating [I'm Sorry, I'm Not Sorry]...
  [•] Inquiring tracks...[done]
   • [01 What We Had]
      | ➤ Collating sources...
      |  ➤ [•] YouTube Music...[success, found 4 sources]
      | ➤ Awaiting audiofeeds...[done]
      | [✓] Got album art
      | [✓] Got raw track file
      | [•] Post Processing...
   • [02 Reason To Stay]
      | ➤ Collating sources...
      |  ➤ [•] YouTube Music...[success, found 6 sources]
      | ➤ Awaiting audiofeeds...[done]
      | [✓] Got album art
      | [✓] Got raw track file
      | [•] Post Processing...
   • [03 Nothing Ever Changes]
      | ➤ Collating sources...
      |  ➤ [•] YouTube Music...[success, found 4 sources]
      | ➤ Awaiting audiofeeds...[done]
      | [✓] Got album art
      | [✓] Got raw track file
      | [•] Post Processing...
   • [04 Love's a Waste]
      | ➤ Collating sources...
      |  ➤ [•] YouTube Music...[success, found 4 sources]
      | ➤ Awaiting audiofeeds...[done]
      | [✓] Got album art
      | [✓] Got raw track file
      | [•] Post Processing...
 [•] Download Complete
 [•] Embedding Metadata...
  • [✓] 01 What We Had
  • [✓] 02 Reason To Stay
  • [✓] 03 Nothing Ever Changes
  • [✓] 04 Love's a Waste
[•] Collation Complete
========== Stats ==========
 [•] Runtime: [2m 2.3s]
 [•] Total queries: [01]
 [•] Total tracks: [04]
     » Skipped: [00]
     ✓ Passed:  [04]
     ✕ Failed:  [00]
 [•] Output directory: [.]
 [•] Cover Art: cover.png (640x640)
 [•] Total Output size: 29.79 MB
 [•] Total Network Usage: 13.35 MB
     ♫ Media: 12.73 MB
     ➤ Album Art: 619.43 KB
 [•] Output bitrate: 320k
===========================

⁠Download a Deezer Artist

freyr https://www.deezer.com/us/artist/14808825

    ____
   / __/_______  __  _______
  / /_/ ___/ _ \/ / / / ___/
 / __/ /  /  __/ /_/ / /
/_/ /_/   \___/\__, /_/
              /____/ v0.1.0

freyr v0.1.0 - (c) Miraculous Owonubi <[email protected]>
-------------------------------------------------------------
Checking directory permissions...[done]
[https://www.deezer.com/us/artist/14808825]
 [•] Identifying service...[Deezer]
 [•] Checking authentication...[authenticated]
 Detected [artist]
 Obtaining artist metadata...[done]
  ➤ Artist: Mazie
  ➤ Followers: 6
  > Gathering collections...[done]
 [•] Collating...
  (01) [i think i wanna be alone] (single)
   [•] Inquiring tracks...[done]
    • [01 i think i wanna be alone]
       | ➤ Collating sources...
       |  ➤ [•] YouTube Music...[success, found 2 sources]
       | ➤ Awaiting audiofeeds...[done]
       | [✓] Got album art
       | [✓] Got raw track file
       | [•] Post Processing...
  (02) [no friends] (single)
   [•] Inquiring tracks...[done]
    • [01 no friends]
       | ➤ Collating sources...
       |  ➤ [•] YouTube Music...[success, found 4 sources]
       | ➤ Awaiting audiofeeds...[done]
       | [✓] Got album art
       | [✓] Got raw track file
       | [•] Post Processing...
 [•] Download Complete
 [•] Embedding Metadata...
  • [✓] 01 i think i wanna be alone
  • [✓] 01 no friends
[•] Collation Complete
========== Stats ==========
 [•] Runtime: [54.6s]
 [•] Total queries: [01]
 [•] Total tracks: [02]
     » Skipped: [00]
     ✓ Passed:  [02]
     ✕ Failed:  [00]
 [•] Output directory: [.]
 [•] Cover Art: cover.png (640x640)
 [•] Total Output size: 8.47 MB
 [•] Total Network Usage: 3.66 MB
     ♫ Media: 3.50 MB
     ➤ Album Art: 157.16 KB
 [•] Output bitrate: 320k
===========================

⁠Batch downloads

⁠via Arguments

Queries can be collated to be processed at once.

freyr query1 query2 ... queryN

⁠via Batch File

Queries can be batched into a file and loaded all at once with the -i, --input <FILE> flag. Queries should be on separate lines.

Lines starting with a # are treated as comments and ignored. comments can also be inlined with everything following the # character ignored.

# ./queue.txt

# Hailee Steinfeld
https://open.spotify.com/track/5Gu0PDLN4YJeW75PpBSg9p # (track) Let Me Go
https://open.spotify.com/track/7GCVboEDzfL3NKp1NrAgHR # (track) Wrong Direction

# (album) Rina Sawayama
https://open.spotify.com/album/3stadz88XVpHcXnVYMHc4J

freyr -i ./queue.txt

Use the --help⁠ flag to see full usage documentation.

⁠URIs

Services can be queried with short URIs containing the type and ID for the resource.

identifier		type		id
URI Short Tags ⁠	:	track	:	~
album
artist
playlist

Use the urify subcommand to parse betweeen URIs and its equivalent URL representation, and vice-versa. Creating freyr-compatible queue output.

freyr urify https://open.spotify.com/album/2D23kwwoy2JpZVuJwzE42B --no-header --no-logo --no-tag

spotify:album:2D23kwwoy2JpZVuJwzE42B
[+] Urify complete

freyr urify -i queue_of_urls.txt -o queue_of_uris.txt --no-header --no-logo

[+] Urify complete
Successfully written to [queue_of_uris.txt]

Examples⁠

⁠Features

Multi-service support [See Service Support⁠]
Playlist generation (per playlist (default) / per query (optional))
Batch download from queue file
Simultaneous chunked downloads (powered by [libxget-js⁠])
Efficient concurrency
Bitrate specification (valid: 96, 128, 160, 192, 256, 320)
Album art embedding & export
Proper track organisation i.e FOLDER/<Artist Name>/<Album Name>/<Track Name>
Resilient visual progressbar per track download (powered by [xprogress⁠])
Stats on runtime completion
- runtime duration
- number of successfully processed tracks
- output directory
- cover art name
- total output size
- total network usage
- network usage for media
- network usage for album art
- output bitrate

⁠Configuration

User / Session specific configuration

Persistent configuration such as authentication keys and their validity period are stored within a session specific configuration file.

This configuration file resides within the user config directory per-platform. e.g $HOME/.config/FreyrCLI/d3fault.x4p for Linux.

Project specific configuration

All configuration is to be defined within a conf.json file in the root of the project. This file should be of JSON format and is to be structured as such.

Defaults are in the conf.json⁠ file.

server: <object> The server URL configuration same as on an individual services' callback option.
- hostname: <string>
- port: <number>
- useHttps: <boolean>
concurrency: <object>
- queries: <number> The number of queries to be processed concurrently.
- tracks: <number> The number of tracks to be actively processed in parallel.
- trackStage: <number> The number of tracks to concurrently preprocess before being pushed to the main trackQueue.
- downloader: <number> The number of tracks to be concurrently downloaded in parallel.
- encoder: <number> The total number of tracks to be concurrently undergo encoding.
- embedder: <number> The total number of tracks to be conc

Tag summary

Recent tags

Content type

Image

Digest

sha256:7510f3e3b…

Size

58.5 MB

Last updated

over 2 years ago

docker pull freyrcli/freyrjs