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

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

Guides: Using a cookies file, --> Troubleshooting <--

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

• 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.
• 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

• 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.

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.

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
To exclude all musicbrainz tags, you can add mb* to exclude_tags. (This does not work for other types of tags).

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 / .png

• run pipx upgrade shiradl --pip-args='--upgrade-strategy=eager', as it's likely yt-dlp or something else needs updating
• In case shira can't download songs / you're having other issues:
  • as a temporary measure, you can try these steps
• 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

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

• 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, 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.

• 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.

• 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!
• To contribute, you'll (likely) need a local installation of shira
  • Fork this repo
  • Verify installation prerequisites
  • Install dependencies locally with pip install . (if you know of a better way, lmk)
  • Make changes
  • Open a pull request
• If you're planning on implementing something big / that changes a lot, it's worth opening an issue about it to discuss it first.
• Thanks!