From 071b117459b939b7d4f993030a295c9ab2104b1a Mon Sep 17 00:00:00 2001 From: Ivan Habunek Date: Wed, 23 Feb 2022 21:54:56 +0100 Subject: [PATCH] Generate docs --- .gitignore | 3 +- CHANGELOG.md | 64 ++-- Makefile | 13 + README.md | 280 ++------------- book.css | 20 ++ book.toml | 10 + docs/SUMMARY.md | 15 + docs/advanced.md | 11 + docs/changelog.md | 169 ++++++++++ docs/commands/clips.md | 120 +++++++ docs/commands/download.md | 148 ++++++++ docs/commands/env.md | 31 ++ docs/commands/info.md | 55 +++ docs/commands/videos.md | 108 ++++++ docs/installation.md | 76 +++++ docs/introduction.md | 58 ++++ docs/license.md | 675 +++++++++++++++++++++++++++++++++++++ docs/usage.md | 24 ++ scripts/generate_changelog | 2 +- scripts/generate_docs | 203 +++++++++++ setup.py | 3 + twitchdl/console.py | 42 +-- 22 files changed, 1824 insertions(+), 306 deletions(-) create mode 100644 book.css create mode 100644 book.toml create mode 100644 docs/SUMMARY.md create mode 100644 docs/advanced.md create mode 100644 docs/changelog.md create mode 100644 docs/commands/clips.md create mode 100644 docs/commands/download.md create mode 100644 docs/commands/env.md create mode 100644 docs/commands/info.md create mode 100644 docs/commands/videos.md create mode 100644 docs/installation.md create mode 100644 docs/introduction.md create mode 100644 docs/license.md create mode 100644 docs/usage.md create mode 100755 scripts/generate_docs diff --git a/.gitignore b/.gitignore index 80aa228..4c96bec 100644 --- a/.gitignore +++ b/.gitignore @@ -13,4 +13,5 @@ tmp/ /twitch-dl.1.man /bundle /*.pyz -/pyrightconfig.json \ No newline at end of file +/pyrightconfig.json +/book diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e4e3ec..333dcf7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,11 +3,11 @@ twitch-dl changelog -**1.21.0 (2022-02-27)** +### [1.21.0 (2022-02-27)](https://github.com/ihabunek/twitch-dl/releases/tag/1.21.0) * Add `env` command for printing environment info for attaching to bug reports -**1.20.0 (2022-02-25)** +### [1.20.0 (2022-02-25)](https://github.com/ihabunek/twitch-dl/releases/tag/1.20.0) * Add `--json` option to `videos` command (#92, thanks @miff2000) * Add `--all` option to `videos` and `clips` commands to list all clips or @@ -15,66 +15,66 @@ twitch-dl changelog * Modify how `--pager` works, will make multiple requests if needed to show all available items, ignoring `--limit`. -**1.19.0 (2022-02-05)** +### [1.19.0 (2022-02-05)](https://github.com/ihabunek/twitch-dl/releases/tag/1.19.0) * Add support for downloading audio only (#10) -**1.18.1 (2022-02-05)** +### [1.18.1 (2022-02-05)](https://github.com/ihabunek/twitch-dl/releases/tag/1.18.1) * Fix issues with output formats (#87, #89) * Fix issues when downloading clip with no game set (#78) * Add option to use clip slug in `--output` format -**1.18.0 (2022-01-25)** +### [1.18.0 (2022-01-25)](https://github.com/ihabunek/twitch-dl/releases/tag/1.18.0) * Add `--output` option to `download` command which allows setting output file template (#70) * Ask to overwrite before downloading to avoid later prompt -**1.17.1 (2022-01-19)** +### [1.17.1 (2022-01-19)](https://github.com/ihabunek/twitch-dl/releases/tag/1.17.1) * Upgrade m3u8 lib to 1.0.0+ -**1.17.0 (2021-12-03)** +### [1.17.0 (2021-12-03)](https://github.com/ihabunek/twitch-dl/releases/tag/1.17.0) * Fix speed calculation when resuming download (#75, thanks CroquetteTheThe) * Add artist and title metadata to resulting video (#80) -**1.16.1 (2021-07-31)** +### [1.16.1 (2021-07-31)](https://github.com/ihabunek/twitch-dl/releases/tag/1.16.1) * Fix compat with older versions of python (#71) -**1.16.0 (2021-06-09)** +### [1.16.0 (2021-06-09)](https://github.com/ihabunek/twitch-dl/releases/tag/1.16.0) * Fix clips download caused by Twitch changes (#64, thanks to all participants) -**1.15.0 (2021-02-15)** +### [1.15.0 (2021-02-15)](https://github.com/ihabunek/twitch-dl/releases/tag/1.15.0) * Add support for new format of clip slug (thanks @Loveangel1337) -**1.14.1 (2021-01-14)** +### [1.14.1 (2021-01-14)](https://github.com/ihabunek/twitch-dl/releases/tag/1.14.1) * Handle videos which don't exist more gracefully -**1.14.0 (2021-01-14)** +### [1.14.0 (2021-01-14)](https://github.com/ihabunek/twitch-dl/releases/tag/1.14.0) * Added `info` command for displaying video or clip info (#51) * Don't show there are more videos when there aren't (#52, thanks @scottyallen) * Fixed Twitch regression for getting the access token (#53) -**1.13.1 (2020-11-23)** +### [1.13.1 (2020-11-23)](https://github.com/ihabunek/twitch-dl/releases/tag/1.13.1) * Fixed clip download issue (#45) -**1.13.0 (2020-11-10)** +### [1.13.0 (2020-11-10)](https://github.com/ihabunek/twitch-dl/releases/tag/1.13.0) * Added `clips` command for listing and batch downloading clips (#26) -**1.12.1 (2020-09-29)** +### [1.12.1 (2020-09-29)](https://github.com/ihabunek/twitch-dl/releases/tag/1.12.1) * Fix bug introduced in previous version which broke joining -**1.12.0 (2020-09-29)** +### [1.12.0 (2020-09-29)](https://github.com/ihabunek/twitch-dl/releases/tag/1.12.0) * Added `source` as alias for best available quality (#33) * Added `--no-join` option to `download` to skip ffmpeg join (#36) @@ -82,37 +82,37 @@ twitch-dl changelog for confirmation (#37) * Added `--pager` option to `videos`, don't page by default (#30) -**1.11.0 (2020-09-03)** +### [1.11.0 (2020-09-03)](https://github.com/ihabunek/twitch-dl/releases/tag/1.11.0) * Make downloading more robust, fixes issues with some VODs (#35) * Bundle twitch-dl to a standalone archive, simplifying installation, see installation instructions in README -**1.10.2 (2020-08-11)** +### [1.10.2 (2020-08-11)](https://github.com/ihabunek/twitch-dl/releases/tag/1.10.2) * Fix version number displayed by `twitch-dl --version` (#29) -**1.10.1 (2020-08-09)** +### [1.10.1 (2020-08-09)](https://github.com/ihabunek/twitch-dl/releases/tag/1.10.1) * Fix videos incorrectly identified as clips (#28) * Make download command work with video URLs lacking 'www' before 'twitch.tv' * Print an error when video or clip is not found instead of an exception trace -**1.10.0 (2020-08-07)** +### [1.10.0 (2020-08-07)](https://github.com/ihabunek/twitch-dl/releases/tag/1.10.0) * Add `--quality` option to `download` command, allows specifying the video quality to download. In this case, twitch-dl will require no user input. (#22) * Fix download of clips which contain numbers in their slug (#24) * Fix URL to video displayed by `videos` command (it was missing /videos/) -**1.9.0 (2020-06-10)** +### [1.9.0 (2020-06-10)](https://github.com/ihabunek/twitch-dl/releases/tag/1.9.0) * **Breaking**: wrongly named `--max_workers` option changed to `--max-workers`. The shorthand option `-w` remains the same. * Fix bug where `videos` command would crash if there was no game info (#21) * Allow unicode characters in filenames, no longer strips e.g. cyrillic script -**1.8.0 (2020-05-17)** +### [1.8.0 (2020-05-17)](https://github.com/ihabunek/twitch-dl/releases/tag/1.8.0) * Fix videos command (#18) * **Breaking**: `videos` command no longer takes the `--offset` parameter due to @@ -120,50 +120,50 @@ twitch-dl changelog * Add paging to `videos` command to replace offset * Add `--game` option to `videos` command to filter by game -**1.7.0 (2020-04-25)** +### [1.7.0 (2020-04-25)](https://github.com/ihabunek/twitch-dl/releases/tag/1.7.0) * Support for specifying broadcast type when listing videos (#13) -**1.6.0 (2020-04-11)** +### [1.6.0 (2020-04-11)](https://github.com/ihabunek/twitch-dl/releases/tag/1.6.0) * Support for downloading clips (#15) -**1.5.1 (2020-04-11)** +### [1.5.1 (2020-04-11)](https://github.com/ihabunek/twitch-dl/releases/tag/1.5.1) * Fix VOD naming issue (#12) * Nice console output while downloading -**1.5.0 (2020-04-10)** +### [1.5.0 (2020-04-10)](https://github.com/ihabunek/twitch-dl/releases/tag/1.5.0) * Fix video downloads after Twitch deprecated access token access * Don't print errors when retrying download, only if all fails -**1.4.0 (2019-08-23)** +### [1.4.0 (2019-08-23)](https://github.com/ihabunek/twitch-dl/releases/tag/1.4.0) * Fix usage of deprecated v3 API * Use m3u8 lib for parsing playlists * Add `--keep` option not preserve downloaded VODs -**1.3.1 (2019-08-13)** +### [1.3.1 (2019-08-13)](https://github.com/ihabunek/twitch-dl/releases/tag/1.3.1) * No changes, bumped to fix issue with pypi -**1.3.0 (2019-08-13)** +### [1.3.0 (2019-08-13)](https://github.com/ihabunek/twitch-dl/releases/tag/1.3.0) * Add `--sort` and `--offset` options to `videos` command, allows paging (#7) * Show video URL in `videos` command output -**1.2.0 (2019-07-05)** +### [1.2.0 (2019-07-05)](https://github.com/ihabunek/twitch-dl/releases/tag/1.2.0) * Add `--format` option to `download` command for specifying the output format (#6) * Add `--version` option for printing program version -**1.1.0 (2019-06-06)** +### [1.1.0 (2019-06-06)](https://github.com/ihabunek/twitch-dl/releases/tag/1.1.0) * Allow limiting download by start and end time -**1.0.0 (2019-04-30)** +### [1.0.0 (2019-04-30)](https://github.com/ihabunek/twitch-dl/releases/tag/1.0.0) * Initial release diff --git a/Makefile b/Makefile index e07945a..c9a3540 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,5 @@ +.PHONY: docs + default : clean dist dist : @@ -33,3 +35,14 @@ test: changelog: ./scripts/generate_changelog > CHANGELOG.md + +docs: changelog + python scripts/generate_docs + mdbook build + +docs-serve: + python scripts/generate_docs + mdbook serve --port 8000 + +docs-deploy: docs + rsync --archive --compress --delete --stats book/ bezdomni:web/twitch-dl diff --git a/README.md b/README.md index 8a25896..0d95033 100644 --- a/README.md +++ b/README.md @@ -9,292 +9,60 @@ multiple concurrent connections to make the download faster. Resources --------- -* Homepage: https://github.com/ihabunek/twitch-dl -* Issues: https://github.com/ihabunek/twitch-dl/issues -* Python package: https://pypi.org/project/twitch-dl/ +* [Documentation](https://twitch-dl.bezdomni.net/) +* [Source code](https://github.com/ihabunek/twitch-dl) +* [Issues](https://github.com/ihabunek/twitch-dl/issues) +* [Python package](https://pypi.org/project/twitch-dl/) Requirements ------------ -* Python 3.5+ +* Python 3.5 or later * [ffmpeg](https://ffmpeg.org/download.html), installed and on the system path -Installation ------------- +Quick start +----------- -### Download standalone archive +See [installation instructions](https://twitch-dl.bezdomni.net/installation.html) +to set up twitch-dl. -Go to the [latest release](https://github.com/ihabunek/twitch-dl/releases/latest) -and download the `twitch-dl..pyz` archive. - -Run the archive by either: - -a) passing it to python: - -``` -python3 twitch-dl.1.13.0.pyz --help -``` - -b) making it executable and invoking it directly (linux specific): - -``` -chmod +x twitch-dl.1.13.0.pyz -./twitch-dl.1.13.0.pyz --help -``` - -Feel free to rename the archive to something more managable, like `twitch-dl`. - -To upgrade to a newer version, repeat the process with the newer release. - -### From PYPI using pipx - -**pipx** is a tool which installs python apps into isolated environments, which -prevents all kinds of problems later so it's the suggested way to install -twitch-dl from PYPI. - -Install pipx as described in -[pipx install docs](https://pipxproject.github.io/pipx/installation/). - -Install twitch-dl: - -``` -pipx install twitch-dl -``` - -Check installation worked: - -``` -twitch-dl --help -``` - -If twitch-dl executable is not found, check that the pipx binary location (by -default `~/.local/bin`) is in your PATH. - -To upgrade twitch-dl to the latest version: - -``` -pipx install twitch-dl -``` - -Usage ------ - -This section does an overview of available features. - -To see a list of available commands run: - -``` -twitch-dl --help -``` - -And to see description and all arguments for a given command run: - -``` -twitch-dl --help -``` - -### Print clip or video info - -Videos can be referenced by URL or ID: - -``` -twitch-dl info 863849735 -twitch-dl info https://www.twitch.tv/videos/863849735 -``` - -Clips by slug or ID: - -``` -twitch-dl info BusyBlushingCattleItsBoshyTime -twitch-dl info https://www.twitch.tv/bananasaurus_rex/clip/BusyBlushingCattleItsBoshyTime -``` - -Shows info about the video or clip as well as download URLs for clips and -playlist URLs for videos. - -### Listing videos - -List recent channel videos (10 by default): +List videos from a channel. ``` twitch-dl videos bananasaurus_rex ``` -Limit to videos of one or more games: +List clips from a channel. ``` -twitch-dl videos --game "doom eternal" --game "cave story" bananasaurus_rex +twitch-dl clips bananasaurus_rex ``` -List all channel videos at once: +Download a video by URL. ``` -twitch-dl videos bananasaurus_rex --all +twitch-dl download https://www.twitch.tv/videos/1418494769 ``` -List all channel videos in pages of 10: +or by ID ``` -twitch-dl videos bananasaurus_rex --pager +twitch-dl download 1418494769 ``` -Page size can be adjusted by passing number of items per page: +Download a clip by URL ``` -twitch-dl videos bananasaurus_rex --pager 5 +twitch-dl download https://www.twitch.tv/bananasaurus_rex/clip/PlacidColdClipsdadDeIlluminati-hL2s_aLE4CHvVN4J ``` -Returns all videos as a JSON list. Useful for scripting. +or by slug ``` -twitch-dl videos bananasaurus_rex --json --all +twitch-dl download PlacidColdClipsdadDeIlluminati-hL2s_aLE4CHvVN4J ``` -### Downloading videos - -Download a video by ID or URL: - -``` -twitch-dl download 221837124 -twitch-dl download https://www.twitch.tv/videos/221837124 -``` - -Specify video quality to download: - -``` -twitch-dl download -q 720p 221837124 -``` - -Setting quality to `source` will download the best available quality: - -``` -twitch-dl download -q source 221837124 -``` - -Setting quality to `audio_only` will download only audio: - -``` -twitch-dl download -q audio_only 221837124 -``` - -### Overriding file name - -The target filename can be defined by passing the `--output` option followed by -the desired file name, e.g. `--output strim.mkv`. - -The filename uses -[Python format string syntax](https://docs.python.org/3/library/string.html#format-string-syntax) -and may contain placeholders in curly braces which will be replaced with -relevant information tied to the downloaded video. - -The supported placeholders are: - -| Placeholder | Description | Example | -| ----------------- | ------------------------------ | ------------------------------ | -| `{id}` | Video ID | 1255522958 | -| `{title}` | Video title | Dark Souls 3 First playthrough | -| `{title_slug}` | Slugified video title | dark_souls_3_first_playthrough | -| `{datetime}` | Video date and time | 2022-01-07T04:00:27Z | -| `{date}` | Video date | 2022-01-07 | -| `{time}` | Video time | 04:00:27Z | -| `{channel}` | Channel name | KatLink | -| `{channel_login}` | Channel login | katlink | -| `{format}` | File extension, see `--format` | mkv | -| `{game}` | Game name | Dark Souls III | -| `{game_slug}` | Slugified game name | dark_souls_iii | -| `{slug}` | Clip slug (clips only) | AbrasivePlacidCatDxAbomb | - -A couple of examples: - -Pattern: `"{date}_{id}_{channel_login}_{title_slug}.{format}"`
-Expands to: `2022-01-07_1255522958_katlink_dark_souls_3_first_playthrough.mkv`
-*This is the default.* - -Pattern: `"{channel} - {game} - {title}.{format}"`
-Expands to: `KatLink - Dark Souls III - Dark Souls 3 First playthrough.mkv` - -### Listing clips - -Listing clips works similar to listing videos. Shows 10 clips by default. Use -`--all` to list all in one go or `--pager` to show them in pages. - -List clips for the given period: - -``` -twitch-dl clips bananasaurus_rex --period last_week -``` - -Supported periods are: `last_day`, `last_week`, `last_month`, `all_time`. - -Also supports JSON output: - -``` -twitch-dl clips bananasaurus_rex --json --all -``` - -Note that this may make multiple requests to the server because each request is -limited to 100 clips, so it may take a little while. You can use `--debug` to -log requests. - -### Downloading clips - -Download a clip by slug or URL: - -``` -twitch-dl download VenomousTameWormHumbleLife -twitch-dl download https://www.twitch.tv/bananasaurus_rex/clip/VenomousTameWormHumbleLife -``` - -Specify clip quality to download: - -``` -twitch-dl download -q 720 VenomousTameWormHumbleLife -``` - -Note that twitch names for clip qualities have no trailing "p". - -### Batch downloading clips - -It's possible to download all clips for a given period: - -``` -twitch-dl clips bananasaurus_rex --period last_week --download -``` - -Clips are downloaded in source quality. - -A note about clips ------------------- - -Currently it doesn't seem to be possible to get a list of clips ordered by time -of creation, only by view count. Clips with the same view count seem to be -returned in random order. This can break paging resulting in duplicate clips -listed or clips missed. - -When batch downloading a large number of clips (over 100), it's possible that -some will be missed. - -Temporary files ---------------- - -By default, twitch-dl will download VODs to your systems temp dir (e.g. `/tmp/` -on Linux). To change the location where the files are downloaded you can set -the `TMP` environment variable, e.g. - -``` -TMP=/my/tmp/path/ twitch-dl download 221837124 -``` - -Man page --------- - -Building the man page for twitch-dl requires scdoc. - -The source is in ``twitch-dl.1.scd``, and you can build it by running: - -``` -make man -``` +For more info see [the documentation](https://twitch-dl.bezdomni.net/usage.html). License ------- @@ -302,3 +70,9 @@ License Copyright 2018-2022 Ivan Habunek Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html + +Useful links for dev +-------------------- + +* https://supersonichub1.github.io/twitch-graphql-api/index.html +* https://github.com/SuperSonicHub1/twitch-graphql-api diff --git a/book.css b/book.css new file mode 100644 index 0000000..a2cea5a --- /dev/null +++ b/book.css @@ -0,0 +1,20 @@ +/* Overrides for the docs theme */ +table { width: 100% } +table th { text-align: left } +code { white-space: pre } +h2, h3 { margin-top: 2.5rem; } +h4, h5 { margin-top: 2rem; } + +td.code { + font-family: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace !important; + font-size: 0.875em; + width: 20%; + white-space: nowrap; +} + +/* Override max width */ +.searchbar-outer, +.searchresults-outer, +.content main { + max-width: 1024px; +} diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..e549eb7 --- /dev/null +++ b/book.toml @@ -0,0 +1,10 @@ +[book] +title = "twitch-dl Documentation" +description = "CLI tool for downloading videos from twitch.tv" +author = "Ivan Habunek" +language = "en" +multilingual = false +src = "docs" + +[output.html] +additional-css = ["book.css"] diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..ad9dae1 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,15 @@ +# Summary + +[Introduction](introduction.md) + +- [Installation](installation.md) +- [Usage](usage.md) + - [twitch-dl download](commands/download.md) + - [twitch-dl videos](commands/videos.md) + - [twitch-dl clips](commands/clips.md) + - [twitch-dl info](commands/info.md) + - [twitch-dl env](commands/env.md) +- [Advanced](advanced.md) + +[License](license.md) +[Changelog](changelog.md) diff --git a/docs/advanced.md b/docs/advanced.md new file mode 100644 index 0000000..8277537 --- /dev/null +++ b/docs/advanced.md @@ -0,0 +1,11 @@ +# Advanced + +## Temporary files + +By default, twitch-dl will download VODs to your systems temp dir (e.g. `/tmp/` +on Linux). To change the location where the files are downloaded you can set +the `TMP` environment variable, e.g. + +``` +TMP=/my/tmp/path/ twitch-dl download 221837124 +``` diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..333dcf7 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,169 @@ +twitch-dl changelog +=================== + + + +### [1.21.0 (2022-02-27)](https://github.com/ihabunek/twitch-dl/releases/tag/1.21.0) + +* Add `env` command for printing environment info for attaching to bug reports + +### [1.20.0 (2022-02-25)](https://github.com/ihabunek/twitch-dl/releases/tag/1.20.0) + +* Add `--json` option to `videos` command (#92, thanks @miff2000) +* Add `--all` option to `videos` and `clips` commands to list all clips or + videos in one go. +* Modify how `--pager` works, will make multiple requests if needed to show all + available items, ignoring `--limit`. + +### [1.19.0 (2022-02-05)](https://github.com/ihabunek/twitch-dl/releases/tag/1.19.0) + +* Add support for downloading audio only (#10) + +### [1.18.1 (2022-02-05)](https://github.com/ihabunek/twitch-dl/releases/tag/1.18.1) + +* Fix issues with output formats (#87, #89) +* Fix issues when downloading clip with no game set (#78) +* Add option to use clip slug in `--output` format + +### [1.18.0 (2022-01-25)](https://github.com/ihabunek/twitch-dl/releases/tag/1.18.0) + +* Add `--output` option to `download` command which allows setting output file + template (#70) +* Ask to overwrite before downloading to avoid later prompt + +### [1.17.1 (2022-01-19)](https://github.com/ihabunek/twitch-dl/releases/tag/1.17.1) + +* Upgrade m3u8 lib to 1.0.0+ + +### [1.17.0 (2021-12-03)](https://github.com/ihabunek/twitch-dl/releases/tag/1.17.0) + +* Fix speed calculation when resuming download (#75, thanks CroquetteTheThe) +* Add artist and title metadata to resulting video (#80) + +### [1.16.1 (2021-07-31)](https://github.com/ihabunek/twitch-dl/releases/tag/1.16.1) + +* Fix compat with older versions of python (#71) + +### [1.16.0 (2021-06-09)](https://github.com/ihabunek/twitch-dl/releases/tag/1.16.0) + +* Fix clips download caused by Twitch changes (#64, thanks to all participants) + +### [1.15.0 (2021-02-15)](https://github.com/ihabunek/twitch-dl/releases/tag/1.15.0) + +* Add support for new format of clip slug (thanks @Loveangel1337) + +### [1.14.1 (2021-01-14)](https://github.com/ihabunek/twitch-dl/releases/tag/1.14.1) + +* Handle videos which don't exist more gracefully + +### [1.14.0 (2021-01-14)](https://github.com/ihabunek/twitch-dl/releases/tag/1.14.0) + +* Added `info` command for displaying video or clip info (#51) +* Don't show there are more videos when there aren't (#52, thanks @scottyallen) +* Fixed Twitch regression for getting the access token (#53) + +### [1.13.1 (2020-11-23)](https://github.com/ihabunek/twitch-dl/releases/tag/1.13.1) + +* Fixed clip download issue (#45) + +### [1.13.0 (2020-11-10)](https://github.com/ihabunek/twitch-dl/releases/tag/1.13.0) + +* Added `clips` command for listing and batch downloading clips (#26) + +### [1.12.1 (2020-09-29)](https://github.com/ihabunek/twitch-dl/releases/tag/1.12.1) + +* Fix bug introduced in previous version which broke joining + +### [1.12.0 (2020-09-29)](https://github.com/ihabunek/twitch-dl/releases/tag/1.12.0) + +* Added `source` as alias for best available quality (#33) +* Added `--no-join` option to `download` to skip ffmpeg join (#36) +* Added `--overwrite` option to `download` to overwrite target without prompting + for confirmation (#37) +* Added `--pager` option to `videos`, don't page by default (#30) + +### [1.11.0 (2020-09-03)](https://github.com/ihabunek/twitch-dl/releases/tag/1.11.0) + +* Make downloading more robust, fixes issues with some VODs (#35) +* Bundle twitch-dl to a standalone archive, simplifying installation, see + installation instructions in README + +### [1.10.2 (2020-08-11)](https://github.com/ihabunek/twitch-dl/releases/tag/1.10.2) + +* Fix version number displayed by `twitch-dl --version` (#29) + +### [1.10.1 (2020-08-09)](https://github.com/ihabunek/twitch-dl/releases/tag/1.10.1) + +* Fix videos incorrectly identified as clips (#28) +* Make download command work with video URLs lacking 'www' before 'twitch.tv' +* Print an error when video or clip is not found instead of an exception trace + +### [1.10.0 (2020-08-07)](https://github.com/ihabunek/twitch-dl/releases/tag/1.10.0) + +* Add `--quality` option to `download` command, allows specifying the video + quality to download. In this case, twitch-dl will require no user input. (#22) +* Fix download of clips which contain numbers in their slug (#24) +* Fix URL to video displayed by `videos` command (it was missing /videos/) + +### [1.9.0 (2020-06-10)](https://github.com/ihabunek/twitch-dl/releases/tag/1.9.0) + +* **Breaking**: wrongly named `--max_workers` option changed to `--max-workers`. + The shorthand option `-w` remains the same. +* Fix bug where `videos` command would crash if there was no game info (#21) +* Allow unicode characters in filenames, no longer strips e.g. cyrillic script + +### [1.8.0 (2020-05-17)](https://github.com/ihabunek/twitch-dl/releases/tag/1.8.0) + +* Fix videos command (#18) +* **Breaking**: `videos` command no longer takes the `--offset` parameter due to + API changes +* Add paging to `videos` command to replace offset +* Add `--game` option to `videos` command to filter by game + +### [1.7.0 (2020-04-25)](https://github.com/ihabunek/twitch-dl/releases/tag/1.7.0) + +* Support for specifying broadcast type when listing videos (#13) + +### [1.6.0 (2020-04-11)](https://github.com/ihabunek/twitch-dl/releases/tag/1.6.0) + +* Support for downloading clips (#15) + +### [1.5.1 (2020-04-11)](https://github.com/ihabunek/twitch-dl/releases/tag/1.5.1) + +* Fix VOD naming issue (#12) +* Nice console output while downloading + +### [1.5.0 (2020-04-10)](https://github.com/ihabunek/twitch-dl/releases/tag/1.5.0) + +* Fix video downloads after Twitch deprecated access token access +* Don't print errors when retrying download, only if all fails + +### [1.4.0 (2019-08-23)](https://github.com/ihabunek/twitch-dl/releases/tag/1.4.0) + +* Fix usage of deprecated v3 API +* Use m3u8 lib for parsing playlists +* Add `--keep` option not preserve downloaded VODs + +### [1.3.1 (2019-08-13)](https://github.com/ihabunek/twitch-dl/releases/tag/1.3.1) + +* No changes, bumped to fix issue with pypi + +### [1.3.0 (2019-08-13)](https://github.com/ihabunek/twitch-dl/releases/tag/1.3.0) + +* Add `--sort` and `--offset` options to `videos` command, allows paging (#7) +* Show video URL in `videos` command output + +### [1.2.0 (2019-07-05)](https://github.com/ihabunek/twitch-dl/releases/tag/1.2.0) + +* Add `--format` option to `download` command for specifying the output format + (#6) +* Add `--version` option for printing program version + +### [1.1.0 (2019-06-06)](https://github.com/ihabunek/twitch-dl/releases/tag/1.1.0) + +* Allow limiting download by start and end time + +### [1.0.0 (2019-04-30)](https://github.com/ihabunek/twitch-dl/releases/tag/1.0.0) + +* Initial release + diff --git a/docs/commands/clips.md b/docs/commands/clips.md new file mode 100644 index 0000000..3dc8b95 --- /dev/null +++ b/docs/commands/clips.md @@ -0,0 +1,120 @@ + +# twitch-dl clips + +List or download clips for a channel. + +### USAGE + +``` +twitch-dl clips [FLAGS] [OPTIONS] +``` + +### ARGUMENTS + + + + + + + + +
<channel_name>Name of the channel to list clips for.
+ +### FLAGS + + + + + + + + + + + + + + + + + + +
-a, --allFetch all videos, overrides --limit
-j, --jsonShow results as JSON. Ignores --pager.
-d, --downloadDownload all videos in given period (in source quality)
+ +### OPTIONS + + + + + + + + + + + + + + + + + + +
-l, --limitNumber of videos to fetch (default 10, max 100)
-P, --periodPeriod from which to return clips. Defaults to all_time. Possible values: last_day, last_week, last_month, all_time.
-p, --pagerNumber of clips to show per page. Disabled by default.
+ + + +## Listing clips + +By default returns top 10 clips of all time. + +``` +twitch-dl clips bananasaurus_rex +``` + +Increase the number of clips returned. + +``` +twitch-dl clips bananasaurus_rex --limit 50 +``` + +Return all clips, may require multiple requests, see notes. + +``` +twitch-dl clips bananasaurus_rex --all +``` + +Return clips from past day/week/month by changing the period: + +``` +twitch-dl clips bananasaurus_rex --period past_week +``` + +List all clips, 10 clips at the time: + +``` +twitch-dl clips bananasaurus_rex --pager +``` + +Print clips data in JSON. Useful for scripting. + +``` +twitch-dl clips bananasaurus_rex --json +``` + +Download all clips of the past week, won't overwrite exisitng ones: + +``` +twitch-dl clips bananasaurus_rex --download --period last_week +``` + +## Notes + +Clips are fetched in batches no larger than 100. When requesting more than 100 +clips, it takes more than one request so it can take a little time. You can see +individual requests by passing the `--debug` flag. + +Currently it doesn't seem to be possible to get a list of clips ordered by time +of creation, only by view count. Clips with the same view count seem to be +returned in random order. This can break paging resulting in duplicate clips +listed or clips missed. \ No newline at end of file diff --git a/docs/commands/download.md b/docs/commands/download.md new file mode 100644 index 0000000..5254006 --- /dev/null +++ b/docs/commands/download.md @@ -0,0 +1,148 @@ + +# twitch-dl download + +Download a video or clip. + +### USAGE + +``` +twitch-dl download