Skip to content

Latest commit

 

History

History
217 lines (155 loc) · 14.3 KB

README.md

File metadata and controls

217 lines (155 loc) · 14.3 KB

Youtube-DL rust cli interface (ytdlr)

A CLI interface for youtube-dl (or yt-dlp available in PATH as youtube-dl) written in RUST.

Also contains some helper functions like rethumbnailing.

Requirements

  • Linux / Mac - build with POSIX system paths in mind (Windows might work)
  • yt-dlp above 2023.03.03*1 and be accessable via the command yt-dlp
  • ffmpeg is installed and be accessable via the command ffmpeg
  • libsqlite3-0(ubuntu) or core/sqlite(arch) needs to be present

Notes:

  • *1 it is recommended to use the latest version available for yt-dlp

Building requirements

  • rust stable 1.70 profile minimal or higher is needed
  • build-essentail(ubuntu) or base-devel(arch) needs to be installed
  • libsqlite3-dev(ubuntu) or core/sqlite(arch) needs to be installed
  • git needs to be available (required by build-script)

Usage

Global Options

Signature: ytdlr [OPTIONS] <SUBCOMMAND>

(Options for main command, must be set before the subcommands)

Short Long Environment Variable Default Type Description
-h --help flag Print Help Information
--archive YTDL_ARCHIVE OsStr The Archive Path to use for a Archive
--color flag Enable Color Output (Currently unused)
--debugger flag Request a VSCode CodeLLDB Debugger before continuing
--tmp YTDL_TMP tmpdir + ytdl_rust_tmp OsStr The Temporary Directory to use for storing intermediate Files
-v --verbosity YTDL_VERBOSITY 0 occurences / number Set the logging verbosity (same as RUST_LOG)
-V --version flag Print the Version

Notes:

  • debugger only works in a target with debug_assertions enabled.
  • verbosity is counted by occurences in the command (like -vv equals 2) or a number in the environment variable. (0 - WARN, 1 - INFO, 2 - DEBUG, 3 - TRACE)
  • archive is only used when a path is set.

download

Command to download 1 or more URLS with youtube-dl / yt-dlp with extra archive support and edit functionality

Signature: download [OPTIONS] [URLS]...
Aliases: download

Positional Name Short Long Environment Variable Default Type Description
-h --help flag Print Help Information
-a --audio-only flag Set that the Output will only be audio-only (mp3)
--audio-editor YTDL_AUDIO_EDITOR OsStr Audio Editor Command / Path to use (like audacity)
--video-editor YTDL_VIDEO_EDITOR OsStr Video Editor Command / Path to use (like kdenlive)
--tagger YTDL_TAGGER OsStr Tagger Command / Path to use (like picard)
--player YTDL_PLAYER OsStr Media Player Command / Path to use (like mpv)
--youtubedl-log flag Enable Output of the youtube-dl command stdout to be printed to the log
--youtubedl-logfile flag Save Youtube-DL logs to a file. File will be in the temporary directory, named "yt-dl_PID.log" where the PID is the ytdlr's pid
--no-reapply-thumbnail YTDL_DISABLE_REAPPLY_THUMBNAIL false bool Disable re-applying the thumbnail after a editor has run
-o --output-path YTDL_OUT DownloadDir + ytdlr-out OsStr Output path to place all finished files in
--archive-mode default enum Set which entries should be output to the youtube-dl archive
--no-check-recovery flag Disables allowing 0 URL's to just check the recovery
--open-tagger flag Set to automatically open the tagger in the end. also overwrites the default option of moving for non-interactive mode
--edit-action enum Apply a single action to all media in the edit stage
--sub-langs YTDL_SUB_LANGS string Set which subtitles to download / embed, see yt-dl(p) subtitle options for what is accepted
--extra-ytdl-args String Add extra youtube-dl arguments
URLS string The URLS (one or more) to be downloaded (or 0 for error recovery)

Notes:

  • This command will store all intermediate downloaded files (until moved) in the tempoarary path specified by --tmp.
  • Files will not be moved to output-path when the Tagger option is chosen (enable "Move Files" in your Tagger).
  • *-stdout flags enable stdout to be printed to the logs, but to view these RUST_LOG must at least be at trace (or -vvv).
  • 0 URLs means to only check for recovery
  • in non-interactive mode the default for finishing media is to move files (m in interactive mode), can be changed with --open-tagger
  • if no "sub-langs" are specified, no subtitles will be downloaded and embedded
  • the fist subtitle stream is set as "default"
  • --extra-ytdl-args requires the use of =, otherwise clap interprets it as a ytldr arguments, like --extra-ytdl-args="--max-downloads 10"
  • --extra-ytdl-args can be provided infinite times to add extra arguments
  • --extra-ytdl-args needs to be used once for each extra arguments, like --extra-ytdl-args="--max-downloads 10" --extra-ytdl-args="--another-option"

archive-mode

The download option --archive-mode sets which archive entries are output for the youtube-dl archive from the SQLite archive.
This option does not have any effect when no archive is provided.
This option does not affect which entries are added to the SQLite archive (only the generated youtube-dl archive)

Possible values are:

  • default: Use the default Archive-Mode, currently corresponds to "all"
  • all: Dump the full SQLite archive as a youtube-dl archive
  • byDate1000: Output the newest 1000 media elements from the archive
  • none: Dont add any entries from the SQLite archive to the youtube-dl archive

Note: none of the options affect the creation of a youtube-dl archive, only which entries are added before the youtube-dl command is run.

rethumbnail

Command to re-apply a image onto a media file as a thumbnail
Input images that are not JPG will be transformed into JPG (most thumbnail-able formats only accept jpg)

Signature: re-thumbnail [OPTIONS] --image <INPUT_IMAGE_PATH> --media <INPUT_MEDIA_PATH>
Aliases: re-thumbnail, rethumbnail

Short Long Environment Variable Default Type Description
-h --help flag Print Help Information
-i --image OsStr Input Image File
-m --media OsStr Input Media File
-o --out Same as --media OsStr Output Media File

Notes:

  • if no --out is specified, by default it will overwrite the input --media path
  • this command does not require youtube-dl to be present, but ffmpeg is required

completions

Command to generate shell completions. Supported shells are all that clap_complete support, which currently are (also lowercased):

  • Bash
  • Elvish
  • Fish
  • PowerShell
  • Zsh

Signature: completions --shell <SHELL_NAME> [--out <PATH>]
Aliases: re-thumbnail, rethumbnail

Short Long Environment Variable Default Type Description
-s --shell string Shell to generate completions for
-o --out OsStr Path to output the completions to

Notes:

  • if no output path (--out) is provided, it will be output to STDOUT
  • this command does not require youtube-dl or ffmpeg to be present

archive import

Command to import a archive into the currently set one
Will Error if Archive Path is unset

Signature: archive import <FILE_PATH>
Aliases: import

Positional Name Short Long Environment Variable Default Type Description
-h --help flag Print Help Information
FILE_PATH OsStr File to Import

Currently supported formats that can be imported:

  • JSON Archive (from previous versions)
  • youtube-dl (provider, id) Archive
  • SQLite Archive

Notes:

  • this command does not require youtube-dl or ffmpeg to be present

archive search

Search the archive for given search parameters Will Error if Archive Path is unset

Signature: archive search [OPTIONS] <QUERIES>...
Aliases: import

Positional Name Short Long Environment Variable Default Type Description
-l --limit 10 number Set the limit for returned values
-f --result-format normal enum Set which format the resulting values are printed in
QUERIES String, String Key-Value pairs of Queries where the key is the column

Supported Columns are:

  • Provider
  • Title
  • MediaId, id
  • InsertedAt, inserted

column names are case-insensitive

Supported Output formats are:

  • Normal: custom formatting [provider:media_id] [inserted_at] title
  • CSVC: CSV, comma delimited provider,media_id,inserted_at,title
  • CSVT: CSV, tab delimited provider\tmedia_id\tinserted_at\ttitle

Supported Date range operators (default: =): > < >= <= =

Examples:

ytdlr archive search title="Some Good Title"
ytdlr archive search title=sometitle
ytdlr archive search "title=Some Good Title"
ytdlr archive search inserted=">=2023-04"
ytdlr archive search provider=youtube title="bug"

Notes

This Project is mainly a personal project, so it is currently tailored to my use-cases, but issues / requests will still be reviewed.

Project TODO

Currently there is nothing to-do.