shira

A smart music downloader

Download music from YouTube, YouTube Music and Soundcloud,
with great metadata and little effort.

Installation

Have python (3.11+) and git installed
Have ffmpeg installed (See Installing ffmpeg) and added to PATH, or specify it with --ffmpeg-location/config
git clone https://github.com/KraXen72/shira, cd shira
pip install -r requirements.txt

On some systems, you might have to use the python3 or python3.x command instead of python
Guides: Using a cookies file, Troubleshooting

Usage Examples

python -m shiradl https://music.youtube.com/watch?v=HdX2COsY2Xk YouTube Music
python -m shiradl "https://music.youtube.com/watch?v=8YwKlPH93Ps&list=PLC1og_v3eb4jE0bmdkWtizrSQ4zt86-3D"
python -m shiradl https://www.youtube.com/watch?v=X0-AvRA7kB0 YouTube (video)
python -m shiradl https://soundcloud.com/neffexmusic/fight-back SoundCloud
python -m shiradl https://music.youtube.com/playlist?list=PLC1og_v3eb4jE0bmdkWtizrSQ4zt86-3D Album/Playlist
python -m shiradl -u ./links.txt List of links to download
- See all cli options/flags

Goals

Provide an easy way to download audio from YouTube Music, YouTube or SoundCloud
- Instead of a GUI/manual input for some steps like in tiger, shira requires no additional user input once ran.
Provide objectively correct or at least very reasonable music metadata & properly tag music files.
- objectively correct: Shira queries the MusicBrainz Database and YouTube Music's API to get metadata
- very reasonable: When downloading a Youtube video, tags will be inferred from the video info: title, channel_name, description, upload_date, etc.

Tagging

Adds a lot of metadata to music files, in these native tags (m4a, mp3)
Embeds proper m4a (iTunes) and .mp3 (ID3v2.4) tags with mediafile
Uses YouTube Music's API to get info.
Uses MusicBrainz API to resolve MusicBrainz ID's from their api
- track, album, artist, albumartist ids
  - falls back to artist, albumartist if this recording can't be found, but artist can.
uses my custom smart-metadata system from tiger for non-music videos
- collects as much information as possible for each tag, and selects the value with most occurences (with fallbacks)
Cleans up messy titles into more reasonable ones:
- IDOL【ENGLISH EDM COVER】「アイドル」 by ARTIST【Artist1 x @Artist2 】 =>
- IDOL [ENGLISH EDM COVER] [アイドル] by ARTIST
Is smart about turning a video's thumbnail into a square album cover

More info about YouTube thumbnail to Album Art algorithm

samples 4 pixels near the corners of the thumbnail (which is first smoothed and reduced to 64 colors)
decides to crop if average of standard deviations of r, g and b color channels from each sample point is lower than a than a treshold
otherwise pads the image to 1:1 with it's dominant color

About & Credits

This software is for educational purposes only and comes without any warranty; See LICENSE.
Credits for copyright-free example tracks used: Andy Leech, 4lienetic, NEFFEX
The name Shira was inspired by a saber-toothed tiger from Ice Age.
It also means 'poetry', 'singing' or 'music' in Hebrew.
The project is based on my previous YouTube downloader tiger and Glomatico's YouTube Music Downloader
Project logo is based on this DeviantArt fanart, which has been modified, vectorised and cleaned up.

Support development

Any donations are highly appreciated! <3

Configuration

Shira can be configured using the command line arguments or the config file.
The config file is created automatically when you run shira for the first time at ~/.shiradl/config.json on Linux and %USERPROFILE%\.shiradl\config.json on Windows. Config file values can be overridden using command line arguments.

Command line argument / Config file key	Description	Default value
`-f`, `--final-path` / `final_path`	Path where the downloaded files will be saved.	`./YouTube Music`
`-t`, `--temp-path` / `temp_path`	Path where the temporary files will be saved.	`./temp`
`-c`, `--cookies-location` / `cookies_location`	Location of the cookies file.	`null`
`--ffmpeg-location` / `ffmpeg_location`	Location of the FFmpeg binary.	`ffmpeg`
`--config-location` / -	Location of the config file.	`<home folder>/.shiradl/config.json`
`-i`, `--itag` / `itag`	Itag (audio quality/format). More info	`140`
`--cover-size` / `cover_size`	Size of the cover. `size >= 0` and `<= 16383`	`1200`
`--cover-format` / `cover_format`	Format of the cover. `jpg` or `png`	`jpg`
`--cover-quality` / `cover_quality`	JPEG quality of the cover. [1<=x<=100]	`94`
`--cover-img` / `cover_img`	Path to image or folder of images. More info	`null`
`--cover-crop` / `cover_crop`	'crop' takes a 1:1 square from the center, pad always pads top & bottom. `auto`, `crop` or `pad`	`auto` - More info
`--template-folder` / `template_folder`	Template of the album folders as a format string.	`{albumartist}/{album}`
`--template-file` / `template_file`	Template of the track files as a format string.	`{track:02d} {title}`
`-e`, `--exclude-tags` / `exclude_tags`	List of tags to exclude from file tagging separated by commas without spaces.	`null`
`--truncate` / `truncate`	Maximum length of the file/folder names.	`40`
`-l`, `--log-level` / `log_level`	Log level.	`INFO`
`-s`, `--save-cover` / `save_cover`	Save cover as a separate file.	`false`
`-o`, `--overwrite` / `overwrite`	Overwrite existing files.	`false`
`-p`, `--print-exceptions` / `print_exceptions`	Print exceptions.	`false`
`-u`, `--url-txt` / -	Read URLs as location of text files containing URLs.	`false`
`-n`, `--no-config-file` / -	Don't use the config file.	`false`
`-w`, `--single-folder` / -	Wrap singles in their own folder instead of placing them directly into artist's folder.	`false`

Itags

The following itags are available:

140 (128kbps AAC) - default, because it's the result of bestaudio/best on a free account
141 (256kbps AAC) - use if you have premium alongside --cookies-location
251 (128kbps Opus) - most stuff will error with Failed to check URL 1/1. Better to use 140

SoundCloud will always download in 128kbps MP3

SoundCloud also offers OPUS, which is currently not supported. Some people were complaining that the quality is worse
These are questionable claims at best, but better safe than sorry.

Tag variables

The following variables can be used in the template folder/file and/or in the exclude_tags list:
title, album, artist, albumartist, track, tracktotal, year, date, cover, comments, lyrics, media_type, rating, track, tracktotal, mb_releasetrackid, mb_releasegroupid, mb_artistid, mb_albumartistid

Cover formats

Can be either jpg or png.

Cover img

Pass in a path to an image file, and it will get used for all of the links you're currently downloading.
Pass in a path to a folder, and the script will use the first image matching the track/video id and jpeg/png format
- You don't have to create covers for all tracks/videos in the playlist/album/etc.
- SoundCloud will also consider images based on the URL slug instead of id
- for example: https://soundcloud.com/yatashi-gang-63564467/lovely-bastards-yatashigang => lovely-bastards-yatashigang.jpg or .png

Troubleshooting

python: No module named shiradl
- Make sure you are not already in the shiradl directory, e.g. /shira/shiradl. if yes, move up one directory with cd .. and retry.
I really need to run this on python 3.8+ and updating to 3.11+ is not an option
- run pip install typing-extensions and modify tagging.py accordingly:
```
- from typing import NotRequired, TypedDict
+ from typing_extensions import NotRequired, TypedDict
```

Installing ffmpeg

Installing ffmpeg with scoop

Scoop is a package manager for windows. It allows easy installing of programs and their updating from the commandline.
Install scoop by running a powershell command (on their website)
Run scoop install main/ffmpeg
Scoop automatically adds it to path. you can update ffmpeg by doing scoop update and scoop update ffmpeg/*
If installing scoop/with scoop is not an option, continue reading:

Installing ffmpeg on Windows (manual install)

Related: Comprehensive tutorial with screenshots
Download an auto-built zip of latest ffmpeg: download / mirror.
Extract it somewhere, for example into C:\ffmpeg. It's best if the path doesen't have spaces.

Adding ffmpeg to PATH

Look for Edit the system environment variables in the Start Menu, launch it.
Find the Path user variable, click Edit
Click New on the side and enter the path to the ffmpeg\bin folder which has ffmpeg.exe in it, e.g. C:\ffmpeg\bin
Click Ok. To verify that ffmpeg is installed, run ffmpeg -version in the terminal.

Pointing to ffmpeg manually

If you do not want to add ffmpeg to path, you can point to it manually.
Use the config option ffmpeg_location or the cli flag --ffmpeg-location to point to the ffmpeg.exe file.
Keep the ffplay.exe and ffprobe.exe files in the same directory.

Installing ffmpeg on linux

use your distro's package manager to install ffmpeg

Setting a cookies file

By setting a cookies file, you can download age restricted tracks, private playlists and songs in 256kbps AAC if you are a premium user.
You can export your cookies to a file by using this Google Chrome extension or Firefox extension on https://music.youtube.com

Contributing

Please report any bugs in Issues. Pull requests are welcome!
Fork this repo, Follow installation steps, Make changes, Open a pull request

asmorodinov/shira