{"id":15495668,"url":"https://github.com/probablykasper/vidl","last_synced_at":"2025-07-15T19:48:07.728Z","repository":{"id":53549177,"uuid":"105796463","full_name":"probablykasper/vidl","owner":"probablykasper","description":"CLI for downloading video/audio","archived":false,"fork":false,"pushed_at":"2022-09-18T00:26:55.000Z","size":72919,"stargazers_count":5,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T18:51:09.541Z","etag":null,"topics":["audio","cli","downloader","metadata","package","video"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/vidl","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/probablykasper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-04T17:20:51.000Z","updated_at":"2023-04-22T18:42:48.000Z","dependencies_parsed_at":"2022-09-11T10:03:17.625Z","dependency_job_id":null,"html_url":"https://github.com/probablykasper/vidl","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probablykasper%2Fvidl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probablykasper%2Fvidl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probablykasper%2Fvidl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probablykasper%2Fvidl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/probablykasper","download_url":"https://codeload.github.com/probablykasper/vidl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249650887,"owners_count":21306086,"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","downloader","metadata","package","video"],"created_at":"2024-10-02T08:18:27.536Z","updated_at":"2025-04-22T21:04:43.416Z","avatar_url":"https://github.com/probablykasper.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/probablykasper/vidl/master/logo/logo%201000.png\" width=\"100\"\u003e\n\u003c/p\u003e\n\n# vidl\nvidl is a script designed to easily download video/audio from anywere, using yt-dlp. It automatically embeds thumbnails to mp3/mp4/m4a files.\n\nvidl will add metadata to mp3 files if it's found. The `--no-md` option turns this off.\n`title`, `artist` and `year` metadata is added, but if the URL is a playlist, it also adds `album`, `album artist`, `track number`, `track count`.\nIf the title contains \" - \", vidl often uses what comes before and after it as artist and title respectively. The `--dont-extract-md` option turns off this behaviour.\n\n# Installation\n1. Install Python (3.7+ is recommended)\n2. Install [ffmpeg and ffprobe](https://www.ffmpeg.org/)\n3. Run `pip3 install vidl`.\n4. If you're not on macOS or Windows, you need to specify where vidl will download files to in your vidl config file. Run `vidl --config-path` to see where the config file is.\nIf you're on macOS, I recommend [setting up shortcuts for vidl](#macos-shortcut-setup)\n\n# Updating\nvidl is updated by running `pip3 install vidl --upgrade --upgrade-strategy eager`.\nIf vidl is unable to download a URL, it might be because yt-dlp is outdated. The `--upgrade-strategy eager` part updates yt-dlp.\n\n# Uninstall\nRun `pip3 uninstall vidl`.\n\nTo fully uninstall vidl, go to vidl's config file (Run `vidl --config-path` to see where it is) and delete the folder it's in.\n\n# Usage\nExamples:\n`vidl https://www.youtube.com/watch?v=ta_ZVS7HkwI`\n- Downloads the video as mp3, and adds metadata it detects.\n\n`vidl mp3 https://www.youtube.com/watch?v=ta_ZVS7HkwI --no-md`\n- Downloads the video as mp3, without adding metadata.\n\n`vidl`\n- Prints vidl's help menu, which looks like this:\n    ```\n    Download Usage:\n        vidl [format] [options] \u003cURL\u003e\n\n    Download Options:\n        format             bestvideo, bestaudio (default), mp3, mp4, wav, m4a, or opus\n        --no-md            Don't add metadata to downloaded files\n        --no-smart-md      Don't extract artist and song name from title\n        --no-embed         Don't embed thumbnail\n        --no-dl            Don't download anything. Usually used with -v\n        -v, --verbose      Display all logs\n\n    General Options:\n        --version          Show version. vidl -v and vidl version works too\n        -h, --help         Show this help message. vidl help works too\n        --config-path      Show the location of the configuration file\n\n    Update:\n        pip3 install vidl --upgrade --upgrade-strategy eager\n    ```\n\n# Configuration\nvidl has a configuration file, which you can find the location of by running `vidl --config-path`. In it, you can set the download folder and filename template.\n\nIf you screw something up, you can delete the file, and the default will be recreated the next time you run vidl.\n\n# Custom metadata parsing\n\nvidl has a `user_md_parser.py` file. By default, it does nothing, but you can configure it to manipulate metadata of songs you download however you like. In my case, I set the \"Comment\" metadata to \"NCS\" if the title ends with \"[NCS Release]\".\n\nDocumentation for this can be found in the file itself. The file is in the same folder as vidl's config file, which you can find by by running `vidl --config-path`. If you screw something up, you can delete the file, and the default will be recreated the next time you run vidl.\n\n# \u003ca name=\"macos-shortcut-setup\"\u003e\u003c/a\u003eSet up shortcuts for vidl (macOS)\nYou'll be able to select any piece of text, press your chosen shortcut and the link(s) in your selected text will be downloaded! A little tedious to set up, but well worth it.\n\nFirst, we need to create a macOS Service:\n1. Open the Automator app.\n2. Choose File \u003e New, and select Service.\n3. (TLDR; Add `Run Shell Script`) In the window that just popped up, there are two columns on the left (if not, click the `Library` button in the status bar). Select `Utilities` in the first column, and in the second column, drag `Run Shell Script` into the main part of the window.\n4. Make your settings match these:\n\n    ![Service receives selected [URLs] in [any application]. Input is [only URLs]. In your Run Shell Script box; Shell: [/bin/bash]. Pass input: [as arguments]](https://raw.githubusercontent.com/SpectralKH/vidl/master/macos-service-screenshot.png)\n\n    If you want the shortcut to only work in one app, select that app instead of `any application`.\n5. In the text box in the \"Run Shell Script\" box, paste in the following script:\n    ```bash\n    for f in \"$@\"\n    do\n      # behave like a normal terminal window:\n      export PATH=/usr/local/bin:$PATH\n      source ~/.bash_profile\n\n      vidl \"$f\"\n    done\n    ```\n6. Choose File \u003e Save. Type in vidl.\n\nAlmost done, you just need to tie a shortcut to the macOS Service you just created:\n1. Open the System Preferences app.\n2. Go to Keyboard and select the Shortcuts tab.\n3. Select Services from the left column, and locate vidl (should be under Internet). Add your preferred shortcut.\n\n# API Usage\nYou can use Python to download a URL. Example:\n```python\nfrom vidl import config, dl\n\ndef main():\n    config.verify_config()\n    dl.download({\n        # all options are required\n        'url': 'https://www.youtube.com/watch?v=82IZ63TU8Fs'\n        'file_format': 'mp3',\n        'audio_only': True,\n        'no_md': False,\n        'no_thumbnail_embed': False,\n        'no_smart_md': False,\n        'no_dl': False,\n        'verbose': False,\n        'download_folder': config.get_config('download_folder'),\n        'output_template': config.get_config('output_template'),\n    })\nmain()\n```\n\n# Dev Instructions\n\n## Dev Installation\n1. Install Python. You may want to install it using [pyenv](https://github.com/pyenv/pyenv) in order to manage Python versions (If Poetry doesn't detect the right version, you can fix it with pyenv).\n2. Install [ffmpeg and ffprobe](https://www.ffmpeg.org/)\n3. Install [Poetry](https://poetry.eustace.io)\n4. Run `poetry install` to install Python package dependencies.\n5. If you're not on macOS or Windows, you need to specify where vidl will download files to in your vidl config file. Run `vidl --config-path` to see where the config file is.\n\nI recommend running `poetry config virtualenvs.in-project true`, which makes Poetry store your Python virtual environment inside the project folder. Additionally, it lets VSCode's Python extension detect the virtual environment if you set the `python.pythonPath` setting to `${workspaceFolder}/.venv/bin/python` in your settings.\n\n## Running\n```\npoetry run vidl\n```\n\nAn alternative to `poetry run \u003ccommand\u003e` is to run `poetry shell` to enter the virtual environment's Bash CLI, and then run the command on it's own (e.g `vidl`).\n\n## Releasing a new version\n\nFirst of all, consider updating the lockfile dependencies by running `poetry update`, then check if things still work.\n\n1. Bump the version number. `\u003cversion\u003e` can be `patch`, `minor`, `major` or a version number:\n    ```\n    poetry version \u003cversion\u003e\n    ```\n2. Update CHANGELOG.md\n3. Build:\n    ```\n    poetry build\n    ```\n4. Commit and create a git tag\n5. Create GitHub release with release notes and attach the build files\n6. Publish to PyPI:\n    ```\n    poetry publish\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobablykasper%2Fvidl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprobablykasper%2Fvidl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobablykasper%2Fvidl/lists"}