Download music from YouTube, YouTube Music and Soundcloud,
with great metadata and little effort.
- 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
python -m shiradl https://music.youtube.com/watch?v=HdX2COsY2Xk
YouTube Musicpython -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
SoundCloudpython -m shiradl https://music.youtube.com/playlist?list=PLC1og_v3eb4jE0bmdkWtizrSQ4zt86-3D
Album/Playlistpython -m shiradl -u ./links.txt
List of links to download
- 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.
- 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.
- falls back to
- 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
- 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.
Any donations are highly appreciated! <3
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 |
The following itags are available:
140
(128kbps AAC) - default, because it's the result ofbestaudio/best
on a free account141
(256kbps AAC) - use if you have premium alongside--cookies-location
251
(128kbps Opus) - most stuff will error withFailed to check URL 1/1
. Better to use140
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.
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
Can be either jpg
or png
.
- 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
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 withcd ..
and retry.
- Make sure you are not already in the
- 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 modifytagging.py
accordingly:
- from typing import NotRequired, TypedDict + from typing_extensions import NotRequired, TypedDict
- run
- 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
andscoop update ffmpeg
/*
- If installing scoop/with scoop is not an option, continue reading:
- 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.
- Look for
Edit the system environment variables
in the Start Menu, launch it. - Find the
Path
user variable, clickEdit
- Click
New
on the side and enter the path to theffmpeg\bin
folder which hasffmpeg.exe
in it, e.g.C:\ffmpeg\bin
- Click
Ok
. To verify thatffmpeg
is installed, runffmpeg -version
in the terminal.
- 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 theffmpeg.exe
file. - Keep the
ffplay.exe
andffprobe.exe
files in the same directory.
- use your distro's package manager to install
ffmpeg
- 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
- Please report any bugs in Issues. Pull requests are welcome!
- Fork this repo, Follow installation steps, Make changes, Open a pull request