{"id":13835409,"url":"https://github.com/Sagnac/streamsave","last_synced_at":"2025-07-10T07:31:56.872Z","repository":{"id":37485974,"uuid":"363378292","full_name":"Sagnac/streamsave","owner":"Sagnac","description":"mpv script aimed at saving live streams and clipping online videos without encoding.","archived":false,"fork":false,"pushed_at":"2024-07-19T16:05:14.000Z","size":205,"stargazers_count":101,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-14T15:14:20.394Z","etag":null,"topics":["lua","mpv","mpv-script","script"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sagnac.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-01T10:05:46.000Z","updated_at":"2025-04-09T02:04:30.000Z","dependencies_parsed_at":"2024-02-21T15:27:35.615Z","dependency_job_id":"68fd9d19-8f50-4213-a8d1-9a46f6f3c40c","html_url":"https://github.com/Sagnac/streamsave","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"purl":"pkg:github/Sagnac/streamsave","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagnac%2Fstreamsave","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagnac%2Fstreamsave/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagnac%2Fstreamsave/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagnac%2Fstreamsave/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sagnac","download_url":"https://codeload.github.com/Sagnac/streamsave/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sagnac%2Fstreamsave/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264545167,"owners_count":23625404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lua","mpv","mpv-script","script"],"created_at":"2024-08-04T14:01:01.342Z","updated_at":"2025-07-10T07:31:56.643Z","avatar_url":"https://github.com/Sagnac.png","language":"Lua","readme":"# [streamsave.lua](https://raw.githubusercontent.com/Sagnac/streamsave/master/streamsave.lua \"streamsave.lua\")\n\n[mpv](https://github.com/mpv-player/mpv) script aimed at saving live streams and clipping online videos without encoding.\n\nEssentially a wrapper around mpv's cache dumping commands, the script adds the following functionality:\n\n* Automatic determination of the output file name and format;\n* Option to specify the preferred output directory;\n* Switch between 5 different dump modes:\n  * clip mode;\n  * full/continuous dump;\n  * write from beginning to current position;\n  * write current chapter;\n  * individually write out all chapters to separate files.\n* Prevention of file overwrites;\n* Acceptance of inverted loop ranges, allowing the end point to be set first;\n* Dynamic chapter indicators on the OSC displaying the clipping interval;\n* Option to track HLS packet drops;\n* Automated stream saving;\n* Workaround for some DAI HLS streams served from .m3u8 where the host changes.\n\nBy default the A-B loop points (set using the `l` key in mpv) determine the portion of the cache written to disk.\n\n----\n\nDefault keybinds:\n\n`Ctrl+z` dumps cache to disk\n\n`Alt+z` cycles dump mode\n\n`Alt+x` aligns loop points to keyframes (pressing again will restore the initial loop points)\n\n`Ctrl+x` stops continuous dumping\n\n----\n\nIt is advisable that you set `--demuxer-max-bytes` and `--demuxer-max-back-bytes` to larger values (e.g. at least 1GiB) in order to have a larger cache.\n\nIf you want to use with local files set `cache=yes` in mpv.conf\n\n----\n\nThere's a lighter base version of the script with the automation, packet tracking, chapter modes, and extra script-message features stripped at the [`lite`](../../tree/lite \"lite branch\") branch.\n\n----\n\nmpv's `script-message` command can be used to change settings at runtime and temporarily override the output title or file extension. Boolean-style options (`yes`/`no`) can be cycled by omitting the third argument.\nIf you override the title, the file extension, or the directory, the `revert` argument can be used to set it back to the default value.\n\nExamples:\n```\nscript-message streamsave-marks\nscript-message streamsave-mode continuous\nscript-message streamsave-title \"Global Title\" force\nscript-message streamsave-title \"Example Title\"\nscript-message streamsave-extension .mkv\nscript-message streamsave-extension revert\nscript-message streamsave-path ~/streams\nscript-message streamsave-label range\n```\n\n----\n\n## General Options\n\nOptions are specified in `~~/script-opts/streamsave.conf`\n\nRuntime updates to all user options are also supported via the `script-opts` property by using mpv's `set` or `change-list` input commands and the `streamsave-` prefix.\n\n----\n\n`save_directory` sets the output file directory. Paths with or without a trailing slash are accepted. Don't use quote marks when specifying paths here.\n\nExample: `save_directory=C:\\User Directory`\n\nmpv double tilde paths `~~/` and home path shortcuts `~/` are also accepted. By default files are dumped in the current / present working directory.\n\n----\n\n`dump_mode=continuous` will use dump-cache, setting the initial timestamp to 0 and leaving the end timestamp unset.\n\nUse this mode if you want to dump the entire cache.\u003cbr\u003e\nThis process will continue as packets are read and until the streams change, the player is closed, or the user presses the stop keybind.\n\nUnder this mode pressing the cache-write keybind again will stop writing the first file and initiate another file starting at 0 and continuing as the cache increases.\n\nIf you want continuous dumping with a different starting point use the default A-B mode instead and only set the first loop point then press the cache-write keybind.\n\n`dump_mode=current` will dump the cache from timestamp 0 to the current playback position in the file.\n\n`dump_mode=chapter` will write the current chapter to file.\n\n`dump_mode=segments` writes out all chapters to individual files.\n\nNote that for these last two you must have the chapter(s) you wish to output fully cached in whole prior to writing; the last chapter, however, utilizes continuous writing.\n\nIf you wish to output a single chapter using a numerical input instead you can specify it with a command at runtime:\n```\nscript-message streamsave-chapter 7\n```\n\n----\n\n`fallback_write=yes` enables initiation of full continuous writes under A-B loop mode if no loop points are set.\n\n----\n\nThe `output_label` option allows you to choose how the output filename is tagged.\n\nThe default uses iterated step increments for every file output; i.e. file-1.mkv, file-2.mkv, etc.\n\nThere are 4 other choices:\n\n`output_label=timestamp` will use a Unix timestamp for the file name.\n\n`output_label=range` will tag the file with the A-B loop range instead using the format HH.MM.SS (e.g. file-\\[00.15.00 - 00.20.00\\].mkv)\n\n`output_label=overwrite` will not tag the file and will overwrite any existing files with the same name.\n\n`output_label=chapter` uses the chapter title for the file name if using one of the chapter modes; with this label the script will not check for existing files with the same name so be careful with overwrites.\n\n----\n\nThe `force_extension` option allows you to force a preferred format and sidestep the automatic detection.\n\nIf using this option it is recommended that a highly flexible container is used (e.g. Matroska).\u003cbr\u003e\nThe format is specified as the extension including the dot (e.g. `force_extension=.mkv`).\n\nThis option can be set at runtime with `script-message` by passing `force` as an argument; e.g.:\n```\nscript-message streamsave-extension .mkv force\n```\nThis changes the format for the current stream and all subsequently loaded streams (without `force` the setting is a one-shot setting for the present stream).\n\nIf this option is set, `script-message streamsave-extension revert` will run the automatic determination at runtime; running this command again will reset the extension to what's specified in `force_extension`.\n\nThis option is disabled by default allowing the script to choose between MP4, WebM, and MKV depending on the input format.\n\n----\n\nThe `force_title` option will set the title used for the filename. By default the script uses the `media-title`.\n\nThis is specified without double quote marks in `streamsave.conf`, e.g. `force_title=Example Title`.\n\nThe `output_label` is still used here and file overwrites are prevented if desired. Changing the filename title to the `media-title` is still possible at runtime by using the `revert` argument, as in the `force_extension` example; the secondary `force` argument is supported as well.\n\n[Property expansion](https://mpv.io/manual/master/#property-expansion) is supported for all user-set titles. For example: `force_title=streamsave_${media-title}` in `streamsave.conf`, or `script-message streamsave-title ${duration}` at runtime.\n\n----\n\nThe `range_marks` option allows the script to set temporary chapters at A-B loop points, resulting in visual guides on the OSC.\n\nIf chapters already exist they are stored and cleared whenever any A-B points are set. Once the A-B points are cleared the original chapters are restored. Any chapters added after A-B mode is entered are added to the initial chapter list.\n\nMake sure your build of mpv is up to date or at least includes commit [mpv-player/mpv@`96b246d`](https://github.com/mpv-player/mpv/commit/96b246d9283da99b82800bbd576037d115e3c6e9 \"mpv commit 96b246d\") so that the seekbar chapter indicators/markers update properly on the OSC.\n\nThis option is disabled by default; set `range_marks=yes` in `streamsave.conf` in order to enable it.\n\nYou can also enable this feature at runtime using `script-message streamsave-marks yes`.\n\n----\n\nThe `track_packets=yes` setting adds chapters to positions where packet loss occurs for HLS streams. This gives you a visual sense for where the video is choppy due to low bandwidth or during times of network congestion and makes it easy to preserve continuity and trim around skips which usually cause invalid timestamps.\n\n----\n\n## Automation Options\n\nThese features are mostly meant to be used with live streams.\n\nContrary to general use where you'd typically want a larger cache (clipping streams, saving a full video, writing out everything loaded in memory, etc.), if you're going to be automating any cache writing you probably want a smaller cache size in order to reduce mpv's memory footprint.\n\nThis becomes especially important for long streams, which when coupled with constantly writing out the cache to file could slow things down quite a bit and possibly lead to problems. Under automatic saving mode the stream will continuously write to disk immediately so it's not necessary to use a large cache size.\n\n----\n\nThe `autostart` and `autoend` options are used for automated stream capturing.\n\nSet `autostart=yes` if you want the script to trigger cache writing immediately on stream load.\n\nSet `autoend` to a time format of the form `HH:MM:SS` (e.g. `autoend=01:20:08`) if you want the file writing to stop after that much of the stream has been cached. The `autoend` feature accepts runtime `script-message` commands under the `streamsave-autoend` name.\n\n----\n\nThe `hostchange=yes` setting enables an experimental workaround for DAI HLS .m3u8 streams in which the host changes. If enabled this will result in multiple files being output as the stream reloads.\n\nThe `autostart` option must also be enabled in order to autosave these types of streams.\n\nThis feature accepts associated `script-message` arguments of `yes`, `no`, and `on_demand`.\n\nThe `on_demand` option is a suboption of the `hostchange` option which, if enabled, triggers reloads immediately across segment switches without waiting until playback has reached the end of the last segment.\n\nThis suboption can be toggled at runtime with:\n```\nscript-message streamsave-hostchange on_demand\n```\n\nSee [`6d5c0e0`](https://github.com/Sagnac/streamsave/commit/6d5c0e04472bd04ad91b5148fb0d9ad5bd9bbb72 \"streamsave commit 6d5c0e0\") for more info regarding the `hostchange` feature.\n\n----\n\nThe `quit=HH:MM:SS` setting will set a one shot quit timer at script load, serving as a replacement for `autoend` when using `hostchange`; once the specified time has elapsed the player will exit.\n\nRunning `script-message streamsave-quit HH:MM:SS` at runtime will reset the timer to the specified duration and restart it from the point of input; it can also be disabled entirely by passing `no`.\n\n----\n\nSet `piecewise=yes` if you want to save a stream in parts automatically. This feature will divide a continuous stream into separate output files based on time, which is useful for capturing individual episodic content from a broadcast.\n\nThis option must be used with `autoend` which controls the piece size; set `autoend` to the duration preferred for each output file.\n\nThis could also be helpful for saving long streams on slow systems. On some slower machines dumping a large cache or writing out a large file can bog things down quite a bit until the writing stops, so this allows you to dump the cache periodically according to the time set in autoend.\n\nThis feature also requires `autostart=yes`. Since this is based on start and stop cycles of continuous writing rather than dumping the loaded cache at regular intervals it is not necessary to have a large cache size.\n","funding_links":[],"categories":["Streaming"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSagnac%2Fstreamsave","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSagnac%2Fstreamsave","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSagnac%2Fstreamsave/lists"}