example-embed.conf

# Configuration options in this file are kept separate from
# "example.conf" since they cannot be declared with empty values.
# For actual usage, add these options to your config file.

# 'patreon-dl' allows you to specify external downloaders for embedded videos.
# To do so:
# 1. Declare a section with heading 'embed.downloader.<provider>'.
# 2. In the section, set the 'exec' property to point to the command used for
#    downloading the embedded content, along with any arguments.
#
# Note that external downloaders are not subject to `max.retries` and
# `*.file.exists.action` settings. This is because `patreon-dl` has no control
# over the downloading process nor knowledge about the outcome of it (including
# where and under what name the file was saved).
#
# Also note that external downloaders are not executed when `dry.run` is in
# effect. This is because `patreon-dl` does not create directories in a dry-run
# and external downloaders might throw an error as they try to write in 
# non-existent directories.
#
# Although care is taken to ensure command arguments are properly escaped, you 
# should be aware of the risks involved in running external programs with 
# arguments having arbitrary values (as you will see, certain embed properties
# can be passed as arguments). You should always quote strings.
#
# Example: YouTube
# ----------------
# The following example uses 'yt-dlp' (https://github.com/yt-dlp/yt-dlp) for
# downloading embedded YouTube videos. Although 'patreon-dl' comes with its
# own YouTube downloader, you are free to use other programs.

[embed.downloader.youtube]

# Set the command to execute. Fields enclosed in curly braces will be
# replaced with actual values at runtime. Available fields:
#
# `post.id`: ID of the post containing the embedded video
# `post.url`: URL of the post containing the embedded video
# `embed.provider`: name of the provider
# `embed.provider.url`: link to the provider's site
# `embed.url`: link to the video page supplied by the provider
# `embed.subject`: subject of the video
# `embed.html`: the HTML code that embeds the video player on the Patreon page
# 'cookie': the cookie from downloader options (or empty string if none specified)
# `dest.dir`: the directory where the video should be saved
# 
# So, here, yt-dlp will download the video at 'embed.url' and save it in
# 'dest.dir'. The filename will be determined by the format "%(title)s.%(ext)s"
# (see: https://github.com/yt-dlp/yt-dlp?tab=readme-ov-file#output-template).

exec = yt-dlp -o "{dest.dir}/%(title)s.%(ext)s" "{embed.url}"

# Example: Vimeo
# Out of the box, 'patreon-dl' does not support downloading Vimeo content.
# They are also slightly more complicated to handle than YouTube embeds, since
# 'embed.url' is not always accessible (depends on the embed method used).
# For this purpose, we have a script that you could use to ease the downloading
# process (beta - no guarantees). Note the script ultimately runs yt-dlp to
# perform the actual downloading.

[embed.downloader.vimeo]

# See project source 'bin/patreon-dl-vimeo.js' for full usage
exec = patreon-dl-vimeo -o "{dest.dir}/%(title)s.%(ext)s" --embed-html "{embed.html}" --embed-url "{embed.url}"

# Example: SproutVideo
# Works pretty much the same as Vimeo embed downloader.

[embed.downloader.sproutvideo]

# See project source 'bin/patreon-dl-sprout.js' for full usage
exec = patreon-dl-sprout -o "{dest.dir}/%(title)s.%(ext)s" --embed-html "{embed.html}" --embed-url "{embed.url}"