# Freyr

Download songs from Spotify, Apple Music and Deezer.

[](https://github.com/miraclx) [](https://www.codefactor.io/repository/github/miraclx/freyr-js/overview/master) [](https://github.com/miraclx/freyr-js) [](https://github.com/miraclx/freyr-js/actions/workflows/tests.yml) [](https://www.npmjs.com/package/freyr) [](https://hub.docker.com/r/freyrcli/freyrjs) [](https://github.com/miraclx/freyr-js) [](https://github.com/miraclx/freyr-js) [](https://github.com/miraclx/freyr-js) [](https://github.com/miraclx/freyr-js) [](https://github.com/miraclx/freyr-js) _{Built with ❤︎ by Miraculous Owonubi}

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:

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

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

  ```bash 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...]

Download a Spotify track

Download an Apple Music album

Download a Deezer Artist

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.

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

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

Service Configuration

The conf.json file already includes some API tokens for service authentication and should work right out of the box. [See Project specific configuration]

Return Codes

• 0: OK
• 1: Invalid query
• 2: Invalid flag value
• 3: Invalid / Inexistent configuration file
• 4: Network error
• 5: Error with working directory
• 6: Failed to initialize a freyr instance
• 7: An error occurred checking dependency paths

FilterRules

Filter rules each to be matched against the tracks involved in any operation.

Used as values to the -l, --filter flag or as key-value pairs in the filters array of the configuration file.

Ranges

Syntax: [a][..][[=]b]

Timed Ranges

Examples: duration=60s..=3:40

Previewing filter representation

To preview filter rules specification, use the filter subcommand.

Service Support

Development

Manually Building

Feel free to clone and use in adherance to the license. Pull requests are very much welcome.

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

• 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

Testing

Freyr comes bundled with a lightweight test suite. See TEST.md for instructions on how to run it.

Docker Development

With docker, you can drop into a sandbox that has all the dependencies you need. Without needing to mess around with your host system or install any weird dependencies.

First, you need to either build a local docker image or submit a PR and use the corresponding auto-generated image.

Building A Local Image

The default provided Dockerfile builds minimal alpine images. Average build network usage is ~ 80 MB and disk usage is ~ 180 MB.

git clone https://github.com/miraclx/freyr-js.git freyr
cd freyr
docker build -t freyr-dev .

Working With Remote Images

An alternative to building the docker image locally is to use a remote image. By default, all PRs submitted to this repository get an equivalently tagged docker image for testing.

For example, the PR #214 has a docker image called freyrcli/freyrjs-git:pr-214. And it stays updated with the current state of the branch.

You can then pull the development image for use locally.

docker pull freyrcli/freyrjs-git:pr-214

Once you have a built development image locally, you're ready to go. You can drop into the container by explicitly defining the entrypoint

docker run -it --entrypoint bash freyr-dev

# Alternatively, create a handy alias
alias freyrsh='docker run -it --entrypoint bash freyr-dev'

*: don't forget to replace freyr-dev with the appropriate image name if you pulled one of the auto-generated remote images.

Optionally, you can use these interesting flags to customize the experience.

• -h freyr-dev sets the container hostname to freyr-dev
• -m 1G sets the container memory limit
• -v $PWD:/data mounts the current working directory to /data within the container.
• --cpus 2 limits the container to using 2 CPU cores

The freyr source would be available in the /freyr directory within the container along with a globally registered command freyr for calling the script.

For more information and documentation about docker, please refer to its official site:

• https://www.docker.com/
• https://docs.docker.com/

License

Apache 2.0 © Miraculous Owonubi (@miraclx) \<omiraculous@gmail.com>