documentation update for youtube-dl

Code not updated yet.

This commit was sponsored by Thomas Hochstein on Patreon.

8 files changed, 46 insertions, 30 deletions

diff --git a/CHANGELOG b/CHANGELOG
index 5d40b0ce1..7de6137bc 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,11 @@
+git-annex (6.20171125) UNRELEASED; urgency=medium
+
+  * Use youtube-dl rather than quvi to download media from web pages,
+    since quvi is not being actively developed and youtube-dl supports
+    many more sites.
+
+ -- Joey Hess <id@joeyh.name>  Tue, 28 Nov 2017 13:48:44 -0400
+
 git-annex (6.20171124) unstable; urgency=medium
 
   * Display progress meter when uploading a key without size information,
diff --git a/debian/control b/debian/control
index 9bbe4bade..a20506002 100644
--- a/debian/control
+++ b/debian/control
@@ -107,7 +107,7 @@ Recommends:
 	lsof,
 	gnupg,
 	bind9-host,
-	quvi,
+	youtube-dl,
 	git-remote-gcrypt (>= 0.20130908-6),
 	nocache,
 	aria2,
diff --git a/doc/forum/downloading_mp4_by_default_with_importfeed/comment_1_c9e5a3700764faa33d2c68de6a8236dc._comment b/doc/forum/downloading_mp4_by_default_with_importfeed/comment_1_c9e5a3700764faa33d2c68de6a8236dc._comment
index 23282e835..07691d823 100644
--- a/doc/forum/downloading_mp4_by_default_with_importfeed/comment_1_c9e5a3700764faa33d2c68de6a8236dc._comment
+++ b/doc/forum/downloading_mp4_by_default_with_importfeed/comment_1_c9e5a3700764faa33d2c68de6a8236dc._comment
@@ -8,4 +8,8 @@ option to make it prefer mp4, you can pass it using the annex.quvi-options
 git configuration setting. Or maybe it has a config file. I don't
 know how to configure quvi to do that, but if it's possible to, you should
 be able to get git-annex to run it with that configuration.
+
+Update: Now git-annex uses youtube-dl, so you can use the
+annex.youtube-dl-options git configuration setting to configure youtube-dl
+to download your preferred format.
 """]]
diff --git a/doc/git-annex-addurl.mdwn b/doc/git-annex-addurl.mdwn
index aace42009..28740dfef 100644
--- a/doc/git-annex-addurl.mdwn
+++ b/doc/git-annex-addurl.mdwn
@@ -10,8 +10,8 @@ git annex addurl `[url ...]`
 
 Downloads each url to its own file, which is added to the annex.
 
-When `quvi` is installed, urls are automatically tested to see if they
-point to a video hosting site, and the video is downloaded instead.
+When `youtube-dl` is installed, and the url is to a web page,
+it's used to download any video that the web page embeds.
   
 Urls to torrent files (including magnet links) will cause the content of
 the torrent to be downloaded, using `aria2c`.
@@ -35,7 +35,7 @@ be used to get better filenames.
 
 * `--raw`
 
-  Prevent special handling of urls by quvi, bittorrent, and other
+  Prevent special handling of urls by youtube-dl, bittorrent, and other
   special remotes. This will for example, make addurl
   download the .torrent file and not the contents it points to.
 
diff --git a/doc/git-annex-importfeed.mdwn b/doc/git-annex-importfeed.mdwn
index 241d369af..99eec85a4 100644
--- a/doc/git-annex-importfeed.mdwn
+++ b/doc/git-annex-importfeed.mdwn
@@ -13,9 +13,8 @@ content has not already been added to the repository before, so you can
 delete, rename, etc the resulting files and repeated runs won't duplicate
 them.
 
-When quvi is installed, links in the feed are tested to see if they
-are on a video hosting site, and the video is downloaded. This allows
-importing e.g., YouTube playlists.
+When `youtube-dl` is installed, it's used to download links in the feed.
+This allows importing e.g., YouTube playlists.
 
 To make the import process add metadata to the imported files from the feed,
 `git config annex.genmetadata true`
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index c3aa8b991..6dc06557c 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -1315,10 +1315,19 @@ Here are all the supported configuration settings.
   Options to pass when running wget or curl.
   For example, to force IPv4 only, set it to "-4"
 
-* `annex.quvi-options`
+* `annex.youtube-dl-options`
 
-  Options to pass to quvi when using it to find the url to download for a
-  video.
+  Options to pass to youtube-dl when using it to find the url to download
+  for a video.
+
+  Some options may break git-annex's integration with youtube-dl. For
+  example, the --output option could cause it to store files somewhere
+  git-annex won't find them. Avoid any options that cause youtube-dl
+  to download more than one file, or to store the file anywhere
+  other than the current working directory.
+
+  Note that git-annex runs youtube-dl with --ignore-config, to avoid
+  any configuration file settings that break its integration.
 
 * `annex.aria-torrent-options`
 
diff --git a/doc/tips/downloading_podcasts.mdwn b/doc/tips/downloading_podcasts.mdwn
index 70fbc0277..13b8300db 100644
--- a/doc/tips/downloading_podcasts.mdwn
+++ b/doc/tips/downloading_podcasts.mdwn
@@ -74,8 +74,8 @@ and transferring to your laptop on demand.
 ## youtube playlists
 
 You can also use `git annex importfeed` on youtube playlists. 
-It will use quvi to automatically download the videos linked to
-by the playlist.
+It will use [youtube-dl](https://rg3.github.io/youtube-dl/) to automatically
+download the videos linked to by the playlist.
 
 To download a youtube playlist, you need to find the feed associated with that
 playlist, and pass it to `git annex importfeed`. There does not seem to be
diff --git a/doc/tips/using_the_web_as_a_special_remote.mdwn b/doc/tips/using_the_web_as_a_special_remote.mdwn
index 4c359d3cc..8bd9c7457 100644
--- a/doc/tips/using_the_web_as_a_special_remote.mdwn
+++ b/doc/tips/using_the_web_as_a_special_remote.mdwn
@@ -68,35 +68,31 @@ number takes that many paths from the end.
 
 ## videos
 
-<a name=quvi></a>
+<a name=videos></a>
 
 There's support for downloading videos from sites like YouTube, Vimeo,
-and many more. This relies on [quvi](http://quvi.sourceforge.net/) to find
-urls to the actual videos files.
+and many more. This relies on [youtube-dl](https://rg3.github.io/youtube-dl/)
+to download the videos.
 
-When you have quvi installed, you can just 
+When you have youtube-dl installed, you can just 
 `git annex addurl http://youtube.com/foo` and it will detect that
 it is a video and download the video content for offline viewing.
 
 Later, in another clone of the repository, you can run `git annex get` on
-the file and it will also be downloaded with the help of quvi. This works
+the file and it will also be downloaded with youtube-dl. This works
 even if the video host has transcoded or otherwise changed the video
 in the meantime; the assumption is that these video files are equivalent.
 
-There is an `annex.quvi-options` configuration setting that can be used
+There is an `annex.youtube-dl-options` configuration setting that can be used
 to pass parameters to quvi. For example, you could set `git config
-annex.quvi-options "--format low"` to configure it to download low
-quality videos from YouTube.
-
-Note that for performance reasons, the url is not checked for redirects,
-so some shortened urls will not be detected. You can
-either load the short url in a browser to get the full url, or you
-can force use of quvi with redirect detection, by prepending "quvi:" to the
-url.
-
-To download a youtube playlist, you need to find the feed associated with that
-playlist, and pass it to `git annex importfeed`. There does not seem to be
-an easy link anywhere to get the feed, but you can construct its url
+annex.youtube-dl-options "--format worst"` to configure it to download low
+quality videos from YouTube. Note that the youtube-dl configuration files
+are not read when git-annex runs youtube-dl, to avoid config settings that
+break its integration.
+
+To download a youtube playlist, you need to find the RSS feed associated with
+that playlist, and pass it to `git annex importfeed`. There does not seem to
+be an easy link anywhere to get the RSS feed, but you can construct its url
 manually. For a playlist like
 "https://www.youtube.com/playlist?list=PL4F80C7D2DC8D9B6C", the
 feed is "https://www.youtube.com/feeds/videos.xml?playlist_id=PL4F80C7D2DC8D9B6C"