{"id":13557318,"url":"https://github.com/RijulGulati/yt-audio","last_synced_at":"2025-04-03T11:31:45.978Z","repository":{"id":62590793,"uuid":"233275626","full_name":"RijulGulati/yt-audio","owner":"RijulGulati","description":"A simple, configurable youtube-dl wrapper to download and manage youtube audio","archived":false,"fork":false,"pushed_at":"2020-08-03T16:28:58.000Z","size":82,"stargazers_count":133,"open_issues_count":1,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-31T09:44:41.386Z","etag":null,"topics":["audio","cli","music","youtube-dl"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RijulGulati.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-11T18:09:46.000Z","updated_at":"2024-03-05T20:02:03.000Z","dependencies_parsed_at":"2022-11-04T08:18:23.366Z","dependency_job_id":null,"html_url":"https://github.com/RijulGulati/yt-audio","commit_stats":null,"previous_names":["pseudoroot/yt-audio","grijul/yt-audio"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RijulGulati%2Fyt-audio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RijulGulati%2Fyt-audio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RijulGulati%2Fyt-audio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RijulGulati%2Fyt-audio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RijulGulati","download_url":"https://codeload.github.com/RijulGulati/yt-audio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246993083,"owners_count":20865932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","cli","music","youtube-dl"],"created_at":"2024-08-01T12:04:16.567Z","updated_at":"2025-04-03T11:31:40.968Z","avatar_url":"https://github.com/RijulGulati.png","language":"Python","funding_links":[],"categories":["Python","cli","\u003ca name=\"music\"\u003e\u003c/a\u003eSound and music"],"sub_categories":[],"readme":"# yt-audio\nA simple, configurable, cross-platform youtube-dl wrapper for downloading and managing youtube audio (with added features).\n\n\n## Installation\n- Requires [Python3](https://www.python.org/downloads/) (\u003e=3.5), [youtube-dl](https://github.com/ytdl-org/youtube-dl) and [ffmpeg](https://www.ffmpeg.org/)/[avconv](https://libav.org/) as dependencies.\n\nyt-audio can be installed via [pip](https://pypi.org/project/yt-audio/). Arch Linux users can use [AUR]() as well.\n\n`$ [sudo] pip3 install --upgrade yt-audio`\n\n## Description and Features\nyt-audio is a command-line program that is used download and manage audio from youtube.com. It is a youtube-dl wrapper program, which means it uses youtube-dl as backend for downloading audio. yt-audio tries to make audio/playlist management easy for users. It is cross-platform (Windows/Linux/MacOS).\n\n### Features\n- Configure/Setup your own command-line arguments for managing titles/playlists (See [usage](https://github.com/pseudoroot/yt-audio#custom-arguments) below)\n- Ability to save each audio/playlist to a different directory (directory specified in argument).\n- Option to keep track of already-downloaded playlist titles **with or without archive file**.\n- Manage single/playlist audio(s).\n\n\n## Usage\n    usage: yt-audio [OPTIONS] REQUIRED_ARGS\n\n    A simple, configurable youtube-dl wrapper for downloading and managing youtube audio.\n\n    Required Arguments (Any/all):\n    URL[::DIR]            Video/Playlist URL with (optional) save directory [URL::dir]\n    -e, --example1        Example playlist [Custom]\n    --all                 All [Custom] Arguments\n\n    Optional Arguments:\n    -h, --help            show this help message and exit\n    -v, --version         show version and exit\n    --use-archive         use archive file to track downloaded titles\n    --use-metadata        use metadata to track downloaded titles\n    --output-format [OUTPUT_FORMAT]\n                            File output format\n    --ytdl-args [YTDL_ADDITIONAL_ARGS]\n                            youtube-dl additional arguments\n\n**yt-audio requires either URL or custom argument(s) (or both) as mandatory input(s).**\n\n### Custom Arguments\nyt-audio gives user the ability to setup their own custom arguments for managing/synchronizing audio/playlists. Custom arguments can be configured in yt-audio's *(config.ini)* configuration file.\n\n**IMPORTANT NOTE: The user, if required, will have to copy the [configuration file](https://github.com/pseudoroot/yt-audio/blob/development/config.ini) as it is not copied during installation.**\n\n**Unix/Linux Users:**\nThe default config location is **$XDG_CONFIG_HOME/yt-audio/** directory. In case *$XDG_CONFIG_HOME* is not set, the file can be placed in **$HOME/.config/yt-audio/** directory.\n\n**Windows Users:** The default config location is **C:\\\\Users\\\\\\\u003cuser\u003e\\\\.config\\\\yt-audio**\n\n**Setting up custom arguments**\n\nThe config file *config.ini* has URL_LIST[] option where users can specify arguments with corresponding URL and (optional) save directory. It's format is as follows:\n\n    URL_LIST = [\n                    # \"['-short_arg1','--long_arg1','Help Text/Description']::URL::PATH\"\n\n                    # PATH (optional) specifies output directory for that particular playlist\n                    # PATH should be absoulte directory path\n                    # URL: Complete youtube title/playlist URL\n                    # These arguments are visible in --help\n\n                    # \"['-e','--example1','Example playlist']::URL::PATH\",\n               ]\n\nURL_LIST takes comma-separated string values. Each string value is formed from 3 components:\n\n- CLI Argument - Argument to register. It is written in form: ['-short_arg','--long_arg','Help Text/Description']\n- URL: Youtube playlist/title URL.\n- PATH (optional): Path where this particular playlist/title will be saved. Provide absolute PATH here.\n\nAll custom arguments are visible in --help [`$ yt-audio --help`]\n\nThe default save PATH is **$HOME/Music**.  PATH can be configured by user in config file (OUTPUT_DIRECTORY = \\\u003cdir\u003e). For playlists, one more directory of \\\u003cPlaylistName\u003e is created where all playlist records are saved.\n\n#### Keeping track of downloaded titles/playlists\nyt-audio has an added feature of keeping track of audio files using **file's metadata**. This removes the requirement of additional archive file to store title(s) info (option provided by youtube-dl).\n\nUser can specify any of the two ways to keep track of downloaded titles. (By default, downloaded titles are **not tracked**)\n\n\n_**Using File Metadata**_\n\nTo use file's metadata, pass `--use-metadata` argument to yt-audio. To use metadata everytime, you can set `USE_METADATA = 1` in config file. Metadata method requires following to work:\n- `--add-metadata` argument to youtube-dl (`--add-metadata` argument is added by yt-audio by default. If you don't want this, you can re-configure youtube-dl command in config).\n\n\n_Known limitations of using metadata method_\n- I have tried this method with both MP3 and M4A format. MP3 works fine. M4a does not work.\n\n\n**_Using Archive File_**\n\nTo use archive file method, pass `--use-archive` argument to yt-audio. To use archive file everytime with yt-audio, you can set `USE_ARCHIVE = 1` in config file. This will create 'records.txt' file in title's download location.\n\n`--use-archive` flag simply passes youtube-dl's `--download-archive FILE` argument to youtube-dl. You can pass your own filename to youtube-dl as well with `--ytdl-args \\\"--download-archive FILE\\\"`. More info about ['--ytdl-args'](https://github.com/pseudoroot/yt-audio#passing-additional-paramaters-to-youtube-dl) argument.\n\n    # Enable metadata\n    $ yt-audio --use-metadata [URL/custom_args]\n\n    # Enable archive file - creates records.txt file\n    $ yt-audio --use-archive [URL/custom_args]\n\n    # Enable archive file - creates archive.txt file\n    $ yt-audio --ytdl-args \\\"--download-archive FILE\\\" [URL/custom_args]\n\n\n_If both metadata and archive file are enabled, archive file method is used_\n\n\n#### Title/Playlist-specific PATH\nUser can also specify any arbitrary path for a particular playlist/title. This PATH can be specified as URL::PATH. If PATH is not provided, PATH from config file is used. If no path is present in config, **$HOME/Music** path is used\n\n#### Changing output format\nDownloaded file's output format can be specified with `--output-format` argument. [Output Template](https://github.com/ytdl-org/youtube-dl/blob/master/README.md#output-template). Default output format is `\"%(title)s.%(ext)s\"`\n\n#### Passing additional paramaters to youtube-dl\nyt-audio gives user the flexibility to pass additional parameters to youtube-dl directly from command-line. Additional arguments can be provided with `--ytdl-arguments` yt-audio argument. Arguments passed to `ytdl-arguments` are passed as-it-is to youtube-dl.\n\n    $ yt-audio `--ytdl-args \\\"--download-archive FILE --user-agent UA\\\"`\n\n**NOTE:** Make sure to escape double-quotes **\"** when passing arguments to `--ytdl-args`. Else the arguments passed to `--ytdl-args` will be read as input arguments to yt-audio.\n\n#### Modifying default youtube-dl/helper commands\nThe commands used by yt-audio can be modified from config file. Unusual parameters might break the program. If the parameter is legit and should have (ideally) worked but it didn't, please [raise an issue](https://github.com/pseudoroot/yt-audio/issues/new).\n\n## Usage Examples\n\n    # Synchronizes/downloads --custom1 and --custom2 custom argument URLs and download specified URL as well.\n    $ yt-audio --custom1 --custom2 https://youtube.com/playlist?list=abcxyz\n\n    # Saves playlist to /my/path/p1/\u003cPlaylistName\u003e/ and single audio to /some/another/path\n    $ yt-audio https://youtube.com/playlist?list=abcxyz::/my/path/p1 https://www.youtube.com/watch?v=abcxyz::/some/another/path\n\n    # Adding additional youtube-dl arguments\n    # This will append additional arguments to youtube-dl download command\n    $ yt-audio --ytdl-args \\\"arg1 arg2\\\" https:youtube.com/abc https://youtube.com/xyz::DIR\n\n    # Different output format\n    $ yt-audio --output-format \"%(display_id)s.%(ext)s\" https://youtube.com/...\n\n\n## yt-audio defaults\nThe following commands are used by yt-audio to download and manage audio. The commands are configurable using config file.\n\n**youtube-dl audio download**\n\n    # (-x --print-json -o \"$OUTPUT$\" $URL$) are mandatory\n    $ youtube-dl -x --print-json --audio-format mp3 --audio-quality 0 --add-metadata --embed-thumbnail -o \"$OUTPUT$\" $URL$\n\n**get playlist/URL info**\n\n    $ youtube-dl --flat-playlist -J $PLAYLIST_URL$\n\n**get file's metadata** (used when downloaded titles are tracked using metadata)\n\n    $ ffprobe -v quiet -print_format json -show_format -hide_banner \"$PATH$\"\n\n\n## Limitations\n- Keeping track of downloaded tracks works with youtube.com only (for now).\n\n## Bugs/Issues\nPlease [create](https://github.com/pseudoroot/yt-audio/issues/new) issue for the same.\nI'm open to suggestions as well :)\n\n## Contact\nFeel free get in touch with me via [Email](mailto:grijul@protonmail.ch).\n\n# License\n[MIT](https://github.com/pseudoroot/yt-audio/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRijulGulati%2Fyt-audio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRijulGulati%2Fyt-audio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRijulGulati%2Fyt-audio/lists"}