freyr-js

Demo

Overview

What freyr does

Depending on the URLs you provide freyr, it will;

1. Extract track metadata (title, album, artist, etc.) from the streaming service (Spotify if you provide a Spotify URL).
2. Then, it queries sources (e.g. YouTube), classifies the results to find you the best sounding, most accurate audio and downloads that in the raw format.
3. Next, it processes each track, encoding them in an Apple AAC format (.m4a file extension) at a default bitrate of 320kbps.
4. Then, it embeds all the metadata and the album art into each track.
5. And finally, it organizes all the files into a structured library (example).

Metadata Availability

Here's a list of the metadata that freyr can extract from each streaming service:

Meta Spotify Apple Music Deezer Title ✔ ✔ ✔ Artist ✔ ✔ ✔ Composer ✗ ✔ ✔ Album ✔ ✔ ✔ Genre ✗ ✔ ✔ Track Number ✔ ✔ ✔ Disk Number ✔ ✔ ✔ Release Date ✔ ✔ ✔ Rating ✔ ✔ ✔ Album Artist ✔ ✔ ✔ ISRC ✔ ✔ ✔ Label ✔ ✔ ✔ Copyright ✔ ✔ ✔ Cover Art ✔ ✔ ✔

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

Requirements

Hey there, you might want to consider a cleaner and straight-forward installation method, without having to manually setup the requirements. If so, checkout the Docker installation method

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

nodejs >= v16.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 v16
$ nvm install --lts

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

AtomicParsley >= 20230114

First, download the latest release for your individual platforms here https://github.com/miraclx/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:
  • 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

Please note that YouTube Music must be available in your region for freyr to successfully work, this is because freyr sources raw audio from YouTube Music.

---

First start by ensuring all requirements listed above are satisfied. Thereafter, you can use either of these options to install freyr:

• NPM: npm install -g freyr

• Yarn: yarn global add freyr

• Or you can build from source

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

  % NPM Yarn pull dependencies npm install yarn install install globally npm link yarn link

Docker

For convenience, we provide officially prebuilt images (automated builds from this repository) so you can skip the setup and build process and get right into it.

Image Size:

Usage (docker)

docker run -it --rm -v $PWD:/data freyrcli/freyrjs [options, arguments and queries...]

You can also create a handy alias to skip remembering that whole line everytime

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

The -v $PWD:/data part sets the working directory for freyr to the current working directory. For example, you can use -v ~/Music/freyr:/data to set the work directory and consequently, default save location to ~/Music/freyr.

Please ensure the folder on the host already exists, create it if not. Otherwise, docker autocreates the folder as root and that causes unpleasant Permission Denied issues when you run freyr.

[See Docker Development]

Getting Started

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

…

Download a Spotify track

freyr spotify:track:5FNS5Vj69AhRGJWjhrAd01

…

Download an Apple Music album

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

…

Download a Deezer Artist

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

…

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> (example)
• 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.

• $HOME/.config/FreyrCLI/d3fault.x4p for Linux.
• $HOME/Library/Preferences/FreyrCLI/d3fault.x4p for macOS.

Project specific configuration

All defaults are defined in the conf.json file at the root of the project. This file should be of JSON format and is to be structured as such.

Do not edit this file directly, instead run freyr once and edit the user specific configuration (see above).

• 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: <nu