Bumped version

* Added a new column for restricting filenames

* Adds restrict-filenames to command runner

* Added UI to settings form

docker/selfhosted.Dockerfile

@@ -118,7 +118,7 @@ WORKDIR "/app"
 
 # Set up data volumes
 RUN mkdir -p /config /downloads /etc/elixir_tzdata_data /etc/yt-dlp/plugins && \ 
-  chmod ugo+rw /etc/elixir_tzdata_data /etc/yt-dlp /etc/yt-dlp/plugins
+  chmod ugo+rw /etc/elixir_tzdata_data /etc/yt-dlp /etc/yt-dlp/plugins /usr/local/bin /usr/local/bin/yt-dlp
 
 # set runner ENV
 ENV MIX_ENV="prod"

lib/pinchflat/downloading/media_downloader.ex

@@ -9,6 +9,7 @@ defmodule Pinchflat.Downloading.MediaDownloader do
 
   alias Pinchflat.Repo
   alias Pinchflat.Media
+  alias Pinchflat.Sources
   alias Pinchflat.Media.MediaItem
   alias Pinchflat.Utils.StringUtils
   alias Pinchflat.Metadata.NfoBuilder
@@ -51,6 +52,8 @@ defmodule Pinchflat.Downloading.MediaDownloader do
   # Looks complicated, but here's the key points:
   # - download_with_options runs a pre-check to see if the media item is suitable for download.
   # - If the media item fails the precheck, it returns {:error, :unsuitable_for_download, message}
+  #   - However, if the precheck fails in a way that we think can be fixed by using cookies, we retry with cookies
+  #     and return the result of that
   # - If the precheck passes but the download fails, it normally returns {:error, :download_failed, message}
   #   - However, there are some errors we can recover from (eg: failure to communicate with SponsorBlock).
   #     In this case, we attempt the download anyway and update the media item with what details we do have.
@@ -67,6 +70,8 @@ defmodule Pinchflat.Downloading.MediaDownloader do
   #   - `:unrecoverable` if there was an initial failure and the recovery attempt failed
   #   - `:download_failed` for all other yt-dlp-related downloading errors
   #   - `:unknown` for any other errors, including those not related to yt-dlp
+  # - If we retry using cookies, all of the above return values apply. The cookie retry
+  #   logic is handled transparently as far as the caller is concerned
   defp attempt_download_and_update_for_media_item(media_item, override_opts) do
     output_filepath = FilesystemUtils.generate_metadata_tmpfile(:json)
     media_with_preloads = Repo.preload(media_item, [:metadata, source: :media_profile])
@@ -151,13 +156,48 @@ defmodule Pinchflat.Downloading.MediaDownloader do
 
   defp download_with_options(url, item_with_preloads, output_filepath, override_opts) do
     {:ok, options} = DownloadOptionBuilder.build(item_with_preloads, override_opts)
-    use_cookies = item_with_preloads.source.use_cookies
-    runner_opts = [output_filepath: output_filepath, use_cookies: use_cookies]
+    force_use_cookies = Keyword.get(override_opts, :force_use_cookies, false)
+    source_uses_cookies = Sources.use_cookies?(item_with_preloads.source, :downloading)
+    should_use_cookies = force_use_cookies || source_uses_cookies
 
-    case YtDlpMedia.get_downloadable_status(url, use_cookies: use_cookies) do
-      {:ok, :downloadable} -> YtDlpMedia.download(url, options, runner_opts)
-      {:ok, :ignorable} -> {:error, :unsuitable_for_download}
-      err -> err
+    runner_opts = [output_filepath: output_filepath, use_cookies: should_use_cookies]
+
+    case {YtDlpMedia.get_downloadable_status(url, use_cookies: should_use_cookies), should_use_cookies} do
+      {{:ok, :downloadable}, _} ->
+        YtDlpMedia.download(url, options, runner_opts)
+
+      {{:ok, :ignorable}, _} ->
+        {:error, :unsuitable_for_download}
+
+      {{:error, _message, _exit_code} = err, false} ->
+        # If there was an error and we don't have cookies, this method will retry with cookies
+        # if doing so would help AND the source allows. Otherwise, it will return the error as-is
+        maybe_retry_with_cookies(url, item_with_preloads, output_filepath, override_opts, err)
+
+      # This gets hit if cookies are enabled which, importantly, also covers the case where we
+      # retry a download with cookies and it fails again
+      {{:error, message, exit_code}, true} ->
+        {:error, message, exit_code}
+
+      {err, _} ->
+        err
+    end
+  end
+
+  defp maybe_retry_with_cookies(url, item_with_preloads, output_filepath, override_opts, err) do
+    {:error, message, _} = err
+    source = item_with_preloads.source
+    message_contains_cookie_error = String.contains?(to_string(message), recoverable_cookie_errors())
+
+    if Sources.use_cookies?(source, :error_recovery) && message_contains_cookie_error do
+      download_with_options(
+        url,
+        item_with_preloads,
+        output_filepath,
+        Keyword.put(override_opts, :force_use_cookies, true)
+      )
+    else
+      err
     end
   end
 
@@ -166,4 +206,11 @@ defmodule Pinchflat.Downloading.MediaDownloader do
       "Unable to communicate with SponsorBlock"
     ]
   end
+
+  defp recoverable_cookie_errors do
+    [
+      "Sign in to confirm",
+      "This video is available to this channel's members"
+    ]
+  end
 end

lib/pinchflat/fast_indexing/fast_indexing_helpers.ex

@@ -12,6 +12,7 @@ defmodule Pinchflat.FastIndexing.FastIndexingHelpers do
   alias Pinchflat.Repo
   alias Pinchflat.Media
   alias Pinchflat.Tasks
+  alias Pinchflat.Sources
   alias Pinchflat.Sources.Source
   alias Pinchflat.FastIndexing.YoutubeRss
   alias Pinchflat.FastIndexing.YoutubeApi
@@ -88,12 +89,16 @@ defmodule Pinchflat.FastIndexing.FastIndexingHelpers do
 
   defp create_media_item_from_media_id(source, media_id) do
     url = "https://www.youtube.com/watch?v=#{media_id}"
+    # This is set to :metadata instead of :indexing since this happens _after_ the
+    # actual indexing process. In reality, slow indexing is the only thing that
+    # should be using :indexing.
+    should_use_cookies = Sources.use_cookies?(source, :metadata)
 
     command_opts =
       [output: DownloadOptionBuilder.build_output_path_for(source)] ++
         DownloadOptionBuilder.build_quality_options_for(source)
 
-    case YtDlpMedia.get_media_attributes(url, command_opts, use_cookies: source.use_cookies) do
+    case YtDlpMedia.get_media_attributes(url, command_opts, use_cookies: should_use_cookies) do
       {:ok, media_attrs} ->
         Media.create_media_item_from_backend_attrs(source, media_attrs)
 

lib/pinchflat/metadata/metadata_file_helpers.ex

@@ -9,6 +9,7 @@ defmodule Pinchflat.Metadata.MetadataFileHelpers do
   needed
   """
 
+  alias Pinchflat.Sources
   alias Pinchflat.Utils.FilesystemUtils
 
   alias Pinchflat.YtDlp.Media, as: YtDlpMedia
@@ -66,7 +67,7 @@ defmodule Pinchflat.Metadata.MetadataFileHelpers do
     yt_dlp_filepath = generate_filepath_for(media_item_with_preloads, "thumbnail.%(ext)s")
     real_filepath = generate_filepath_for(media_item_with_preloads, "thumbnail.jpg")
     command_opts = [output: yt_dlp_filepath]
-    addl_opts = [use_cookies: media_item_with_preloads.source.use_cookies]
+    addl_opts = [use_cookies: Sources.use_cookies?(media_item_with_preloads.source, :metadata)]
 
     case YtDlpMedia.download_thumbnail(media_item_with_preloads.original_url, command_opts, addl_opts) do
       {:ok, _} -> real_filepath

lib/pinchflat/metadata/source_metadata_storage_worker.ex

@@ -93,7 +93,7 @@ defmodule Pinchflat.Metadata.SourceMetadataStorageWorker do
   defp determine_series_directory(source) do
     output_path = DownloadOptionBuilder.build_output_path_for(source)
     runner_opts = [output: output_path]
-    addl_opts = [use_cookies: source.use_cookies]
+    addl_opts = [use_cookies: Sources.use_cookies?(source, :metadata)]
     {:ok, %{filepath: filepath}} = MediaCollection.get_source_details(source.original_url, runner_opts, addl_opts)
 
     case MetadataFileHelpers.series_directory_from_media_filepath(filepath) do
@@ -113,6 +113,7 @@ defmodule Pinchflat.Metadata.SourceMetadataStorageWorker do
   defp fetch_metadata_for_source(source) do
     tmp_output_path = "#{tmp_directory()}/#{StringUtils.random_string(16)}/source_image.%(ext)S"
     base_opts = [convert_thumbnails: "jpg", output: tmp_output_path]
+    should_use_cookies = Sources.use_cookies?(source, :metadata)
 
     opts =
       if source.collection_type == :channel do
@@ -121,7 +122,7 @@ defmodule Pinchflat.Metadata.SourceMetadataStorageWorker do
         base_opts ++ [:write_thumbnail, playlist_items: 1]
       end
 
-    MediaCollection.get_source_metadata(source.original_url, opts, use_cookies: source.use_cookies)
+    MediaCollection.get_source_metadata(source.original_url, opts, use_cookies: should_use_cookies)
   end
 
   defp tmp_directory do

lib/pinchflat/settings/setting.ex

@@ -15,7 +15,9 @@ defmodule Pinchflat.Settings.Setting do
     :video_codec_preference,
     :audio_codec_preference,
     :youtube_api_key,
-    :extractor_sleep_interval_seconds
+    :extractor_sleep_interval_seconds,
+    :download_throughput_limit,
+    :restrict_filenames
   ]
 
   @required_fields [
@@ -35,6 +37,9 @@ defmodule Pinchflat.Settings.Setting do
     field :youtube_api_key, :string
     field :route_token, :string
     field :extractor_sleep_interval_seconds, :integer, default: 0
+    # This is a string because it accepts values like "100K" or "4.2M"
+    field :download_throughput_limit, :string
+    field :restrict_filenames, :boolean, default: false
 
     field :video_codec_preference, :string
     field :audio_codec_preference, :string

lib/pinchflat/slow_indexing/slow_indexing_helpers.ex

@@ -132,13 +132,14 @@ defmodule Pinchflat.SlowIndexing.SlowIndexingHelpers do
     {:ok, pid} = FileFollowerServer.start_link()
 
     handler = fn filepath -> setup_file_follower_watcher(pid, filepath, source) end
+    should_use_cookies = Sources.use_cookies?(source, :indexing)
 
     command_opts =
       [output: DownloadOptionBuilder.build_output_path_for(source)] ++
         DownloadOptionBuilder.build_quality_options_for(source) ++
         build_download_archive_options(source, was_forced)
 
-    runner_opts = [file_listener_handler: handler, use_cookies: source.use_cookies]
+    runner_opts = [file_listener_handler: handler, use_cookies: should_use_cookies]
     result = MediaCollection.get_media_attributes_for_collection(source.original_url, command_opts, runner_opts)
 
     FileFollowerServer.stop(pid)

lib/pinchflat/sources/source.ex

@@ -28,7 +28,7 @@ defmodule Pinchflat.Sources.Source do
     series_directory
     index_frequency_minutes
     fast_index
-    use_cookies
+    cookie_behaviour
     download_media
     last_indexed_at
     original_url
@@ -78,7 +78,7 @@ defmodule Pinchflat.Sources.Source do
     field :collection_type, Ecto.Enum, values: [:channel, :playlist]
     field :index_frequency_minutes, :integer, default: 60 * 24
     field :fast_index, :boolean, default: false
-    field :use_cookies, :boolean, default: false
+    field :cookie_behaviour, Ecto.Enum, values: [:disabled, :when_needed, :all_operations], default: :disabled
     field :download_media, :boolean, default: true
     field :last_indexed_at, :utc_datetime
     # Only download media items that were published after this date

lib/pinchflat/sources/sources.ex

@@ -32,6 +32,19 @@ defmodule Pinchflat.Sources do
     source.output_path_template_override || media_profile.output_path_template
   end
 
+  @doc """
+  Returns a boolean indicating whether or not cookies should be used for a given operation.
+
+  Returns boolean()
+  """
+  def use_cookies?(source, operation) when operation in [:indexing, :downloading, :metadata, :error_recovery] do
+    case source.cookie_behaviour do
+      :disabled -> false
+      :all_operations -> true
+      :when_needed -> operation in [:indexing, :error_recovery]
+    end
+  end
+
   @doc """
   Returns the list of sources. Returns [%Source{}, ...]
   """
@@ -181,9 +194,9 @@ defmodule Pinchflat.Sources do
 
   defp add_source_details_to_changeset(source, changeset) do
     original_url = changeset.changes.original_url
-    use_cookies = Ecto.Changeset.get_field(changeset, :use_cookies)
+    should_use_cookies = Ecto.Changeset.get_field(changeset, :cookie_behaviour) == :all_operations
     # Skipping sleep interval since this is UI blocking and we want to keep this as fast as possible
-    addl_opts = [use_cookies: use_cookies, skip_sleep_interval: true]
+    addl_opts = [use_cookies: should_use_cookies, skip_sleep_interval: true]
 
     case MediaCollection.get_source_details(original_url, [], addl_opts) do
       {:ok, source_details} ->

lib/pinchflat/yt_dlp/command_runner.ex

@@ -35,7 +35,7 @@ defmodule Pinchflat.YtDlp.CommandRunner do
 
     output_filepath = generate_output_filepath(addl_opts)
     print_to_file_opts = [{:print_to_file, output_template}, output_filepath]
-    user_configured_opts = cookie_file_options(addl_opts) ++ sleep_interval_opts(addl_opts)
+    user_configured_opts = cookie_file_options(addl_opts) ++ rate_limit_options(addl_opts) ++ misc_options()
     # These must stay in exactly this order, hence why I'm giving it its own variable.
     all_opts = command_opts ++ print_to_file_opts ++ user_configured_opts ++ global_options()
     formatted_command_opts = [url] ++ CliUtils.parse_options(all_opts)
@@ -116,20 +116,6 @@ defmodule Pinchflat.YtDlp.CommandRunner do
     end
   end
 
-  defp sleep_interval_opts(addl_opts) do
-    sleep_interval = Settings.get!(:extractor_sleep_interval_seconds)
-
-    if sleep_interval <= 0 || Keyword.get(addl_opts, :skip_sleep_interval) do
-      []
-    else
-      [
-        sleep_requests: NumberUtils.add_jitter(sleep_interval),
-        sleep_interval: NumberUtils.add_jitter(sleep_interval),
-        sleep_subtitles: NumberUtils.add_jitter(sleep_interval)
-      ]
-    end
-  end
-
   defp add_cookie_file do
     base_dir = Application.get_env(:pinchflat, :extras_directory)
     filename_options_map = %{cookies: "cookies.txt"}
@@ -145,6 +131,32 @@ defmodule Pinchflat.YtDlp.CommandRunner do
     end)
   end
 
+  defp rate_limit_options(addl_opts) do
+    throughput_limit = Settings.get!(:download_throughput_limit)
+    sleep_interval_opts = sleep_interval_opts(addl_opts)
+    throughput_option = if throughput_limit, do: [limit_rate: throughput_limit], else: []
+
+    throughput_option ++ sleep_interval_opts
+  end
+
+  defp sleep_interval_opts(addl_opts) do
+    sleep_interval = Settings.get!(:extractor_sleep_interval_seconds)
+
+    if sleep_interval <= 0 || Keyword.get(addl_opts, :skip_sleep_interval) do
+      []
+    else
+      [
+        sleep_requests: NumberUtils.add_jitter(sleep_interval),
+        sleep_interval: NumberUtils.add_jitter(sleep_interval),
+        sleep_subtitles: NumberUtils.add_jitter(sleep_interval)
+      ]
+    end
+  end
+
+  defp misc_options do
+    if Settings.get!(:restrict_filenames), do: [:restrict_filenames], else: []
+  end
+
   defp backend_executable do
     Application.get_env(:pinchflat, :yt_dlp_executable)
   end

lib/pinchflat_web/controllers/settings/setting_html/setting_form.html.heex

@@ -47,7 +47,21 @@
         placeholder="0"
         type="number"
         label="Sleep Interval (seconds)"
-        help="Sleep interval in seconds between each extractor request. Must be a positive whole number (or set to 0 to disable)"
+        help="Sleep interval in seconds between each extractor request. Must be a positive whole number. Set to 0 to disable"
+      />
+
+      <.input
+        field={f[:download_throughput_limit]}
+        placeholder="4.2M"
+        label="Download Throughput"
+        help="Sets the max bytes-per-second throughput when downloading media. Examples: '50K' or '4.2M'. Leave blank to disable"
+      />
+
+      <.input
+        field={f[:restrict_filenames]}
+        type="toggle"
+        label="Restrict Filenames"
+        help="Restrict filenames to only ASCII characters and avoid ampersands/spaces in filenames"
       />
     </section>
   </section>

lib/pinchflat_web/controllers/sources/source_html.ex

@@ -27,6 +27,14 @@ defmodule PinchflatWeb.Sources.SourceHTML do
     ]
   end
 
+  def friendly_cookie_behaviours do
+    [
+      {"Disabled", :disabled},
+      {"When Needed", :when_needed},
+      {"All Operations", :all_operations}
+    ]
+  end
+
   def cutoff_date_presets do
     [
       {"7 days", compute_date_offset(7)},

lib/pinchflat_web/controllers/sources/source_html/source_form.html.heex

@@ -87,10 +87,11 @@
     />
 
     <.input
-      field={f[:use_cookies]}
-      type="toggle"
-      label="Use Cookies for Downloading"
-      help="Uses your YouTube cookies for this source (if configured). Used for downloading private playlists and videos. See docs for important details"
+      field={f[:cookie_behaviour]}
+      options={friendly_cookie_behaviours()}
+      type="select"
+      label="Cookie Behaviour"
+      help="Uses your YouTube cookies for this source (if configured). 'When Needed' tries to minimize cookie usage except for certain indexing and downloading tasks. See docs"
     />
 
     <section x-show="advancedMode">

lib/pinchflat_web/endpoint.ex

@@ -39,7 +39,10 @@ defmodule PinchflatWeb.Endpoint do
     cookie_key: "request_logger"
 
   plug Plug.RequestId
-  plug Plug.Telemetry, event_prefix: [:phoenix, :endpoint]
+
+  plug Plug.Telemetry,
+    event_prefix: [:phoenix, :endpoint],
+    log: {__MODULE__, :log_level, []}
 
   plug Plug.Parsers,
     parsers: [:urlencoded, :multipart, :json],
@@ -55,6 +58,10 @@ defmodule PinchflatWeb.Endpoint do
 
   plug PinchflatWeb.Router
 
+  # Disables logging in Plug.Telemetry for healthcheck requests
+  def log_level(%Plug.Conn{path_info: ["healthcheck"]}), do: false
+  def log_level(_), do: :info
+
   # URLs need to be generated using the host of the current page being accessed
   # for things like Podcast RSS feeds to contain links to the right location.
   #

lib/pinchflat_web/router.ex

@@ -68,7 +68,7 @@ defmodule PinchflatWeb.Router do
   scope "/", PinchflatWeb do
     pipe_through :api
 
-    get "/healthcheck", HealthController, :check
+    get "/healthcheck", HealthController, :check, log: false
   end
 
   scope "/dev" do

mix.exs

@@ -4,7 +4,7 @@ defmodule Pinchflat.MixProject do
   def project do
     [
       app: :pinchflat,
-      version: "2025.2.20",
+      version: "2025.3.17",
       elixir: "~> 1.17",
       elixirc_paths: elixirc_paths(Mix.env()),
       start_permanent: Mix.env() == :prod,

priv/repo/migrations/20250304185528_add_cookie_behaviour_to_sources.exs

@@ -0,0 +1,18 @@
+defmodule Pinchflat.Repo.Migrations.AddCookieBehaviourToSources do
+  use Ecto.Migration
+
+  def change do
+    alter table(:sources) do
+      add :cookie_behaviour, :string, null: false, default: "disabled"
+    end
+
+    execute(
+      "UPDATE sources SET cookie_behaviour = 'all_operations' WHERE use_cookies = TRUE",
+      "UPDATE sources SET use_cookies = TRUE WHERE cookie_behaviour = 'all_operations'"
+    )
+
+    alter table(:sources) do
+      remove :use_cookies, :boolean, null: false, default: false
+    end
+  end
+end

priv/repo/migrations/20250311222451_add_rate_limit_speed_to_settings.exs

@@ -0,0 +1,9 @@
+defmodule Pinchflat.Repo.Migrations.AddRateLimitSpeedToSettings do
+  use Ecto.Migration
+
+  def change do
+    alter table(:settings) do
+      add :download_throughput_limit, :string
+    end
+  end
+end

priv/repo/migrations/20250317213740_add_restrict_filenames_to_settings.exs

@@ -0,0 +1,9 @@
+defmodule Pinchflat.Repo.Migrations.AddRestrictFilenamesToSettings do
+  use Ecto.Migration
+
+  def change do
+    alter table(:settings) do
+      add :restrict_filenames, :boolean, default: false
+    end
+  end
+end

test/pinchflat/downloading/media_downloader_test.exs

@@ -157,15 +157,16 @@ defmodule Pinchflat.Downloading.MediaDownloaderTest do
           {:ok, ""}
       end)
 
-      source = source_fixture(%{use_cookies: true})
+      source = source_fixture(%{cookie_behaviour: :all_operations})
       media_item = media_item_fixture(%{source_id: source.id})
 
       assert {:ok, _} = MediaDownloader.download_for_media_item(media_item)
     end
 
-    test "does not set use_cookies if the source does not use cookies" do
+    test "does not set use_cookies if the source uses cookies when needed" do
       expect(YtDlpRunnerMock, :run, 3, fn
-        _url, :get_downloadable_status, _opts, _ot, _addl ->
+        _url, :get_downloadable_status, _opts, _ot, addl ->
+          assert {:use_cookies, false} in addl
           {:ok, "{}"}
 
         _url, :download, _opts, _ot, addl ->
@@ -176,14 +177,34 @@ defmodule Pinchflat.Downloading.MediaDownloaderTest do
           {:ok, ""}
       end)
 
-      source = source_fixture(%{use_cookies: false})
+      source = source_fixture(%{cookie_behaviour: :when_needed})
+      media_item = media_item_fixture(%{source_id: source.id})
+
+      assert {:ok, _} = MediaDownloader.download_for_media_item(media_item)
+    end
+
+    test "does not set use_cookies if the source does not use cookies" do
+      expect(YtDlpRunnerMock, :run, 3, fn
+        _url, :get_downloadable_status, _opts, _ot, addl ->
+          assert {:use_cookies, false} in addl
+          {:ok, "{}"}
+
+        _url, :download, _opts, _ot, addl ->
+          assert {:use_cookies, false} in addl
+          {:ok, render_metadata(:media_metadata)}
+
+        _url, :download_thumbnail, _opts, _ot, _addl ->
+          {:ok, ""}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :disabled})
       media_item = media_item_fixture(%{source_id: source.id})
 
       assert {:ok, _} = MediaDownloader.download_for_media_item(media_item)
     end
   end
 
-  describe "download_for_media_item/3 when testing retries" do
+  describe "download_for_media_item/3 when testing non-cookie retries" do
     test "returns a recovered tuple on recoverable errors", %{media_item: media_item} do
       message = "Unable to communicate with SponsorBlock"
 
@@ -277,6 +298,68 @@ defmodule Pinchflat.Downloading.MediaDownloaderTest do
     end
   end
 
+  describe "download_for_media_item/3 when testing cookie retries" do
+    test "retries with cookies if we think it would help and the source allows" do
+      expect(YtDlpRunnerMock, :run, 4, fn
+        _url, :get_downloadable_status, _opts, _ot, [use_cookies: false] ->
+          {:error, "Sign in to confirm your age", 1}
+
+        _url, :get_downloadable_status, _opts, _ot, [use_cookies: true] ->
+          {:ok, "{}"}
+
+        _url, :download, _opts, _ot, addl ->
+          assert {:use_cookies, true} in addl
+          {:ok, render_metadata(:media_metadata)}
+
+        _url, :download_thumbnail, _opts, _ot, _addl ->
+          {:ok, ""}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :when_needed})
+      media_item = media_item_fixture(%{source_id: source.id})
+
+      assert {:ok, _} = MediaDownloader.download_for_media_item(media_item)
+    end
+
+    test "does not retry with cookies if we don't think it would help even the source allows" do
+      expect(YtDlpRunnerMock, :run, 1, fn
+        _url, :get_downloadable_status, _opts, _ot, [use_cookies: false] ->
+          {:error, "Some other error", 1}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :when_needed})
+      media_item = media_item_fixture(%{source_id: source.id})
+
+      assert {:error, :download_failed, "Some other error"} = MediaDownloader.download_for_media_item(media_item)
+    end
+
+    test "does not retry with cookies even if we think it would help but source doesn't allow" do
+      expect(YtDlpRunnerMock, :run, 1, fn
+        _url, :get_downloadable_status, _opts, _ot, [use_cookies: false] ->
+          {:error, "Sign in to confirm your age", 1}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :disabled})
+      media_item = media_item_fixture(%{source_id: source.id})
+
+      assert {:error, :download_failed, "Sign in to confirm your age"} =
+               MediaDownloader.download_for_media_item(media_item)
+    end
+
+    test "does not retry with cookies if cookies were already used" do
+      expect(YtDlpRunnerMock, :run, 1, fn
+        _url, :get_downloadable_status, _opts, _ot, [use_cookies: true] ->
+          {:error, "This video is available to this channel's members", 1}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :all_operations})
+      media_item = media_item_fixture(%{source_id: source.id})
+
+      assert {:error, :download_failed, "This video is available to this channel's members"} =
+               MediaDownloader.download_for_media_item(media_item)
+    end
+  end
+
   describe "download_for_media_item/3 when testing media_item attributes" do
     setup do
       stub(YtDlpRunnerMock, :run, fn

test/pinchflat/fast_indexing/fast_indexing_helpers_test.exs

@@ -104,34 +104,6 @@ defmodule Pinchflat.FastIndexing.FastIndexingHelpersTest do
       FastIndexingHelpers.index_and_kickoff_downloads(source)
     end
 
-    test "sets use_cookies if the source uses cookies" do
-      expect(HTTPClientMock, :get, fn _url -> {:ok, "<yt:videoId>test_1</yt:videoId>"} end)
-
-      stub(YtDlpRunnerMock, :run, fn _url, :get_media_attributes, _opts, _ot, addl ->
-        assert {:use_cookies, true} in addl
-
-        {:ok, media_attributes_return_fixture()}
-      end)
-
-      source = source_fixture(%{use_cookies: true})
-
-      assert [%MediaItem{}] = FastIndexingHelpers.index_and_kickoff_downloads(source)
-    end
-
-    test "does not set use_cookies if the source does not use cookies" do
-      expect(HTTPClientMock, :get, fn _url -> {:ok, "<yt:videoId>test_1</yt:videoId>"} end)
-
-      stub(YtDlpRunnerMock, :run, fn _url, :get_media_attributes, _opts, _ot, addl ->
-        assert {:use_cookies, false} in addl
-
-        {:ok, media_attributes_return_fixture()}
-      end)
-
-      source = source_fixture(%{use_cookies: false})
-
-      assert [%MediaItem{}] = FastIndexingHelpers.index_and_kickoff_downloads(source)
-    end
-
     test "does not enqueue a download job if the media item does not match the format rules" do
       expect(HTTPClientMock, :get, fn _url -> {:ok, "<yt:videoId>test_1</yt:videoId>"} end)
 
@@ -180,6 +152,50 @@ defmodule Pinchflat.FastIndexing.FastIndexingHelpersTest do
     end
   end
 
+  describe "index_and_kickoff_downloads/1 when testing cookies" do
+    test "sets use_cookies if the source uses cookies" do
+      expect(HTTPClientMock, :get, fn _url -> {:ok, "<yt:videoId>test_1</yt:videoId>"} end)
+
+      stub(YtDlpRunnerMock, :run, fn _url, :get_media_attributes, _opts, _ot, addl ->
+        assert {:use_cookies, true} in addl
+
+        {:ok, media_attributes_return_fixture()}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :all_operations})
+
+      assert [%MediaItem{}] = FastIndexingHelpers.index_and_kickoff_downloads(source)
+    end
+
+    test "does not set use_cookies if the source uses cookies when needed" do
+      expect(HTTPClientMock, :get, fn _url -> {:ok, "<yt:videoId>test_1</yt:videoId>"} end)
+
+      stub(YtDlpRunnerMock, :run, fn _url, :get_media_attributes, _opts, _ot, addl ->
+        assert {:use_cookies, false} in addl
+
+        {:ok, media_attributes_return_fixture()}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :when_needed})
+
+      assert [%MediaItem{}] = FastIndexingHelpers.index_and_kickoff_downloads(source)
+    end
+
+    test "does not set use_cookies if the source does not use cookies" do
+      expect(HTTPClientMock, :get, fn _url -> {:ok, "<yt:videoId>test_1</yt:videoId>"} end)
+
+      stub(YtDlpRunnerMock, :run, fn _url, :get_media_attributes, _opts, _ot, addl ->
+        assert {:use_cookies, false} in addl
+
+        {:ok, media_attributes_return_fixture()}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :disabled})
+
+      assert [%MediaItem{}] = FastIndexingHelpers.index_and_kickoff_downloads(source)
+    end
+  end
+
   describe "index_and_kickoff_downloads/1 when testing backends" do
     test "uses the YouTube API if it is enabled", %{source: source} do
       expect(HTTPClientMock, :get, fn url, _headers ->

test/pinchflat/metadata/metadata_file_helpers_test.exs

@@ -88,13 +88,35 @@ defmodule Pinchflat.Metadata.MetadataFileHelpersTest do
       Helpers.download_and_store_thumbnail_for(media_item)
     end
 
+    test "returns nil if yt-dlp fails", %{media_item: media_item} do
+      stub(YtDlpRunnerMock, :run, fn _url, :download_thumbnail, _opts, _ot, _addl -> {:error, "error"} end)
+
+      filepath = Helpers.download_and_store_thumbnail_for(media_item)
+
+      assert filepath == nil
+    end
+  end
+
+  describe "download_and_store_thumbnail_for/2 when testing cookie usage" do
     test "sets use_cookies if the source uses cookies" do
       expect(YtDlpRunnerMock, :run, fn _url, :download_thumbnail, _opts, _ot, addl ->
         assert {:use_cookies, true} in addl
         {:ok, ""}
       end)
 
-      source = source_fixture(%{use_cookies: true})
+      source = source_fixture(%{cookie_behaviour: :all_operations})
+      media_item = Repo.preload(media_item_fixture(%{source_id: source.id}), :source)
+
+      Helpers.download_and_store_thumbnail_for(media_item)
+    end
+
+    test "does not set use_cookies if the source uses cookies when needed" do
+      expect(YtDlpRunnerMock, :run, fn _url, :download_thumbnail, _opts, _ot, addl ->
+        assert {:use_cookies, false} in addl
+        {:ok, ""}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :when_needed})
       media_item = Repo.preload(media_item_fixture(%{source_id: source.id}), :source)
 
       Helpers.download_and_store_thumbnail_for(media_item)
@@ -106,19 +128,11 @@ defmodule Pinchflat.Metadata.MetadataFileHelpersTest do
         {:ok, ""}
       end)
 
-      source = source_fixture(%{use_cookies: false})
+      source = source_fixture(%{cookie_behaviour: :disabled})
       media_item = Repo.preload(media_item_fixture(%{source_id: source.id}), :source)
 
       Helpers.download_and_store_thumbnail_for(media_item)
     end
-
-    test "returns nil if yt-dlp fails", %{media_item: media_item} do
-      stub(YtDlpRunnerMock, :run, fn _url, :download_thumbnail, _opts, _ot, _addl -> {:error, "error"} end)
-
-      filepath = Helpers.download_and_store_thumbnail_for(media_item)
-
-      assert filepath == nil
-    end
   end
 
   describe "parse_upload_date/1" do

test/pinchflat/metadata/source_metadata_storage_worker_test.exs

@@ -254,7 +254,23 @@ defmodule Pinchflat.Metadata.SourceMetadataStorageWorkerTest do
       end)
 
       profile = media_profile_fixture(%{download_source_images: true})
-      source = source_fixture(media_profile_id: profile.id, use_cookies: true)
+      source = source_fixture(media_profile_id: profile.id, cookie_behaviour: :all_operations)
+
+      perform_job(SourceMetadataStorageWorker, %{id: source.id})
+    end
+
+    test "does not set use_cookies if the source uses cookies when needed" do
+      expect(YtDlpRunnerMock, :run, 2, fn
+        _url, :get_source_details, _opts, _ot, _addl ->
+          {:ok, source_details_return_fixture()}
+
+        _url, :get_source_metadata, _opts, _ot, addl ->
+          assert {:use_cookies, false} in addl
+          {:ok, render_metadata(:channel_source_metadata)}
+      end)
+
+      profile = media_profile_fixture(%{download_source_images: true})
+      source = source_fixture(media_profile_id: profile.id, cookie_behaviour: :when_needed)
 
       perform_job(SourceMetadataStorageWorker, %{id: source.id})
     end
@@ -270,7 +286,7 @@ defmodule Pinchflat.Metadata.SourceMetadataStorageWorkerTest do
       end)
 
       profile = media_profile_fixture(%{download_source_images: true})
-      source = source_fixture(media_profile_id: profile.id, use_cookies: false)
+      source = source_fixture(media_profile_id: profile.id, cookie_behaviour: :disabled)
 
       perform_job(SourceMetadataStorageWorker, %{id: source.id})
     end
@@ -323,7 +339,21 @@ defmodule Pinchflat.Metadata.SourceMetadataStorageWorkerTest do
           {:ok, "{}"}
       end)
 
-      source = source_fixture(%{series_directory: nil, use_cookies: true})
+      source = source_fixture(%{series_directory: nil, cookie_behaviour: :all_operations})
+      perform_job(SourceMetadataStorageWorker, %{id: source.id})
+    end
+
+    test "does not set use_cookies if the source uses cookies when needed" do
+      expect(YtDlpRunnerMock, :run, 2, fn
+        _url, :get_source_details, _opts, _ot, addl ->
+          assert {:use_cookies, false} in addl
+          {:ok, source_details_return_fixture()}
+
+        _url, :get_source_metadata, _opts, _ot, _addl ->
+          {:ok, "{}"}
+      end)
+
+      source = source_fixture(%{series_directory: nil, cookie_behaviour: :when_needed})
       perform_job(SourceMetadataStorageWorker, %{id: source.id})
     end
 
@@ -337,7 +367,7 @@ defmodule Pinchflat.Metadata.SourceMetadataStorageWorkerTest do
           {:ok, "{}"}
       end)
 
-      source = source_fixture(%{series_directory: nil, use_cookies: false})
+      source = source_fixture(%{series_directory: nil, cookie_behaviour: :disabled})
       perform_job(SourceMetadataStorageWorker, %{id: source.id})
     end
   end

test/pinchflat/slow_indexing/slow_indexing_helpers_test.exs

@@ -302,14 +302,27 @@ defmodule Pinchflat.SlowIndexing.SlowIndexingHelpersTest do
 
       SlowIndexingHelpers.index_and_enqueue_download_for_media_items(source)
     end
+  end
 
+  describe "index_and_enqueue_download_for_media_items/2 when testing cookies" do
     test "sets use_cookies if the source uses cookies" do
       expect(YtDlpRunnerMock, :run, fn _url, :get_media_attributes_for_collection, _opts, _ot, addl_opts ->
         assert {:use_cookies, true} in addl_opts
         {:ok, source_attributes_return_fixture()}
       end)
 
-      source = source_fixture(%{use_cookies: true})
+      source = source_fixture(%{cookie_behaviour: :all_operations})
+
+      SlowIndexingHelpers.index_and_enqueue_download_for_media_items(source)
+    end
+
+    test "sets use_cookies if the source uses cookies when needed" do
+      expect(YtDlpRunnerMock, :run, fn _url, :get_media_attributes_for_collection, _opts, _ot, addl_opts ->
+        assert {:use_cookies, true} in addl_opts
+        {:ok, source_attributes_return_fixture()}
+      end)
+
+      source = source_fixture(%{cookie_behaviour: :when_needed})
 
       SlowIndexingHelpers.index_and_enqueue_download_for_media_items(source)
     end
@@ -320,7 +333,7 @@ defmodule Pinchflat.SlowIndexing.SlowIndexingHelpersTest do
         {:ok, source_attributes_return_fixture()}
       end)
 
-      source = source_fixture(%{use_cookies: false})
+      source = source_fixture(%{cookie_behaviour: :disabled})
 
       SlowIndexingHelpers.index_and_enqueue_download_for_media_items(source)
     end

test/pinchflat/sources_test.exs

@@ -60,6 +60,33 @@ defmodule Pinchflat.SourcesTest do
     end
   end
 
+  describe "use_cookies?/2" do
+    test "returns true if the source has been set to use cookies" do
+      source = source_fixture(%{cookie_behaviour: :all_operations})
+      assert Sources.use_cookies?(source, :downloading)
+    end
+
+    test "returns false if the source has not been set to use cookies" do
+      source = source_fixture(%{cookie_behaviour: :disabled})
+      refute Sources.use_cookies?(source, :downloading)
+    end
+
+    test "returns true if the action is indexing and the source is set to :when_needed" do
+      source = source_fixture(%{cookie_behaviour: :when_needed})
+      assert Sources.use_cookies?(source, :indexing)
+    end
+
+    test "returns false if the action is downloading and the source is set to :when_needed" do
+      source = source_fixture(%{cookie_behaviour: :when_needed})
+      refute Sources.use_cookies?(source, :downloading)
+    end
+
+    test "returns true if the action is error_recovery and the source is set to :when_needed" do
+      source = source_fixture(%{cookie_behaviour: :when_needed})
+      assert Sources.use_cookies?(source, :error_recovery)
+    end
+  end
+
   describe "list_sources/0" do
     test "it returns all sources" do
       source = source_fixture()
@@ -393,13 +420,13 @@ defmodule Pinchflat.SourcesTest do
       valid_attrs = %{
         media_profile_id: media_profile_fixture().id,
         original_url: "https://www.youtube.com/channel/abc123",
-        use_cookies: true
+        cookie_behaviour: :all_operations
       }
 
       assert {:ok, %Source{}} = Sources.create_source(valid_attrs)
     end
 
-    test "does not set use_cookies to false if the source has not been set to use cookies" do
+    test "does not set use_cookies if the source uses cookies when needed" do
       expect(YtDlpRunnerMock, :run, fn _url, :get_source_details, _opts, _ot, addl ->
         refute Keyword.get(addl, :use_cookies)
 
@@ -409,7 +436,23 @@ defmodule Pinchflat.SourcesTest do
       valid_attrs = %{
         media_profile_id: media_profile_fixture().id,
         original_url: "https://www.youtube.com/channel/abc123",
-        use_cookies: false
+        cookie_behaviour: :when_needed
+      }
+
+      assert {:ok, %Source{}} = Sources.create_source(valid_attrs)
+    end
+
+    test "does not set use_cookies if the source has not been set to use cookies" do
+      expect(YtDlpRunnerMock, :run, fn _url, :get_source_details, _opts, _ot, addl ->
+        refute Keyword.get(addl, :use_cookies)
+
+        {:ok, playlist_return()}
+      end)
+
+      valid_attrs = %{
+        media_profile_id: media_profile_fixture().id,
+        original_url: "https://www.youtube.com/channel/abc123",
+        cookie_behaviour: :disabled
       }
 
       assert {:ok, %Source{}} = Sources.create_source(valid_attrs)

test/pinchflat/yt_dlp/command_runner_test.exs

@@ -96,7 +96,7 @@ defmodule Pinchflat.YtDlp.CommandRunnerTest do
     end
   end
 
-  describe "run/4 when testing sleep interval options" do
+  describe "run/4 when testing rate limit options" do
     test "includes sleep interval options by default" do
       Settings.set(extractor_sleep_interval_seconds: 5)
 
@@ -124,6 +124,22 @@ defmodule Pinchflat.YtDlp.CommandRunnerTest do
       refute String.contains?(output, "--sleep-requests")
       refute String.contains?(output, "--sleep-subtitles")
     end
+
+    test "includes limit_rate option when specified" do
+      Settings.set(download_throughput_limit: "100K")
+
+      assert {:ok, output} = Runner.run(@media_url, :foo, [], "")
+
+      assert String.contains?(output, "--limit-rate 100K")
+    end
+
+    test "doesn't include limit_rate option when download_throughput_limit is nil" do
+      Settings.set(download_throughput_limit: nil)
+
+      assert {:ok, output} = Runner.run(@media_url, :foo, [], "")
+
+      refute String.contains?(output, "--limit-rate")
+    end
   end
 
   describe "run/4 when testing global options" do
@@ -146,6 +162,24 @@ defmodule Pinchflat.YtDlp.CommandRunnerTest do
     end
   end
 
+  describe "run/4 when testing misc options" do
+    test "includes --restrict-filenames when enabled" do
+      Settings.set(restrict_filenames: true)
+
+      assert {:ok, output} = Runner.run(@media_url, :foo, [], "")
+
+      assert String.contains?(output, "--restrict-filenames")
+    end
+
+    test "doesn't include --restrict-filenames when disabled" do
+      Settings.set(restrict_filenames: false)
+
+      assert {:ok, output} = Runner.run(@media_url, :foo, [], "")
+
+      refute String.contains?(output, "--restrict-filenames")
+    end
+  end
+
   describe "version/0" do
     test "adds the version arg" do
       assert {:ok, output} = Runner.version()