| Name | ffmpeg-editlist JSON |
| Version |
0.5.4
JSON |
| download |
| home_page | |
| Summary | Cut and splice video files using a YAML definition file and ffmpeg |
| upload_time | 2024-01-18 22:46:29 |
| maintainer | |
| docs_url | None |
| author | Richard Darst |
| requires_python | |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ffmpeg editlist utility
Often, one wants to reprocess a video file using some basic
operations, such as removing certain segments. Rather than opening a
video editor, it is nice to be able to define a text file (the
**editlist**) with processing instructions, and then run it. This
allows collaboration in the processing, for example sharing the
editlist file via git.
This utility takes a YAML definition of an editlist (segments to cut
out and re-assemble into a file), and does the re-assembling using the
ffmpeg command line utility.
This is currently an alpha-level utility: it works, but expect it may
not exactly fit your use case without a bit of work. Documentation is
minimal but still needs improvement. However, it has been used for
several large events.
Video demonstration: https://youtu.be/thvMNTBJg2Y
Features include:
* YAML edit list definition.
* Select segments to stitch together in the final video file.
Segments are either copied raw or re-encoded (`--reencode`).
* Give Table of Contents times (for example, '16:45: Lesson 2 begins')
relative to the source video, output mapped to times in
the output video automatically.
* Cover certain areas of video (for example, when an audience member
appears).
* Everything scripted and non-interactive.
* Cutting and re-splicing subtitles, too.
## Installation and dependencies
This is on PyPI, may be installed with `pip install ffmpeg-editlist`.
The only dependency is PyYAML so it might be reasonable to install
with `pip install --user`. This creates a `ffmpeg-editlist` command
in your environment.
For usage without installing, `ffmpeg_editlist.py` works as
stand-alone with only `pyyaml`.
It depends on the `ffmpeg` command line utility, which must be
installed through the operating system. Version requirements of
`ffmpeg` are currently unknown.
## Usage
Start with a directory of your videos (example: `day1-raw.mkv`).
Create an edit list file (described in next section). A minimal
example is:
```yaml
- input: day1-raw.mkv
- output: part1.mkv
title: This is the title of part1
description: >-
This is the multi-line description
of part 1.
editlist:
- start: 00:00 # These are time segments to include
- 4:00: Begin exercise 1
- stop: 5:00
- start: 6:13
- -: Going over the exercises # '-' means "latest start time".
- stop: 99:00
```
The general usage is then:
```
python ffmpeg-editlist.py EDITLIST.yaml INPUT-DIR [-o OUTPUT-DIR]
```
Where `INPUT-DIR` is the search path for input files and `OUTPUT-DIR`
(default `.`) is the output path for files. You can use the `--limit
PATTERN` option to reprocess only a few videos (example: `--limit
part1`).
Because of the way keyframes work, there may be missing segments
around the transition points. After you have tested that your timings
seem reasonable, re-run with ``--reencode`` and it will do a full
re-encoding and make a seamless videos. The default encoding settings
are designed to be slow but good enough for all practical purposes:
```
python ffmpeg-editlist.py EDITLIST.yaml --reencode INPUT-DIR [-o OUTPUT-DIR]
```
`OUTPUT-DIR` will get the encoded files, and `.txt` files with the
video descriptions ready to upload to your video hosting site.
Subtitles: The option `--srt` will make ffmpeg-editlist reprocess
subtitles just like video segments (cut to the segments and adjust
timestamps). A `.srt` file is expected alongside each input file
(input file's extension replaced with `.srt`), and an output is
similarly placed alongside each output. Warning: make sure that no
segment's declared stop time goes beyond the actual file length. It's
possible that there will be some weird effects around the
beginning/end of the segments if subtitles go beyond the start/stop.
## Editlist definition
### Minimal example: single file
```yaml
# Input is taken from command line argument `input`.
- output: output.mp4
title: This is the title
description: >-
This is the multi-line description.
editlist:
- start: 00:00 # These are time segments to include
- stop: 5:00
- start: 6:13
- stop: 99:00
```
Run with `python ffmpeg-editlist.py editlist.yaml input.mkv`.
### Minimal example with multiple files
```yaml
- input: raw-day1.mkv
output: day1-part1.mkv
editlist:
- start: 1:12
- stop: 55:30
# Previous input file is used if no new input is defined
- output: day1-part2.mkv
editlist:
- start: 1:00:12
- stop: 1:54:00
```
Run with `python ffmpeg-editlist.py editlist.yaml $input_directory`.
### Multi-file with video descriptions
This is a full example that demonstrates all features.
```yaml
- workshop_description: >
If this exists, it will be appended to the bottom of every video
description. For example, it can be general information about the
overall workshop.
# This input will be used for all segments until redefined
# Input relative to the input-dir command line argument.
# If not given, use the raw input-dir argument as a filename.
- input: cr-2021may-day1-obs.mov
# A basic example
# Output is relative to the output-dir command line argument.
- output: day1-welcome.mp4
# If given, do not reencode this segment even if --reencode is given
# (useful for segments that start at 00:00). 'reencode: true' does
# nothing, this is the default and --reencode must still be
# specified on the command line.
#reencode: false
editlist:
- start: 12:20
- stop: 31:14
# Git-intro day 1
- output: day1-git-intro-1.mp4 # Output filename
title: YouTube Video Title
description: >
Description of the video.
editlist:
# These pairs are times to *include*
- start: 31:14
- stop: 38:13
- start: 41:28
- stop: 1:04:45
# A sample including table of contents entries.
# You need to map times from the raw file, to the output file, in
# order to make a clickable YouTube table of contents.
# They are times in the
# original video, and they are converted to the equivalent times in
# the processed videos. They must be within the ranges above (and
# you get a unhandled error if they aren't):
# segment_start <= toc_time < segment_stop.
# These can be interspersed with the segment definitions.
# Example:
- output: day2-git-intro-2.mp4
editlist:
- start: 31:14
# TOC entry:
- 31:14: Overview of the day
- 33:25: Motivation to version control
- stop: 38:13
- start: 41:28
- -: Basics of version control # '-' is an alias for "last start"
- 48:35: "Exercise: record changes" # has a ':', so must be quoted
- stop: 1:04:45
#- 1:18:22: This will fail, timestamp after the end
This syntax is used to cover a segment of the video:
- output: day3-has-audience-visible.mp4
editlist:
- start: 00:00
# Cover an area. begin/end are clear. w and h are width and
# height. x and y are offset (left, down) from the top-left corner
- cover: {begin: "1:15:29", end: "1:51:34", w: 840, h: 300, x: 360}
- stop: 5:00
```
Alongside the `.mp4` output file, a `.mp4.info.txt` file is created
with these contents. This is designed for easy copying and pasting
into hosting sites:
```
Title of Video
Video description.
01:53 Table of contents entry 1
15:45 Table of contents entry 2
...
Workshop description.
```
### Multiple inputs
Multiple inputs in one segment might be useful when you are attaching
an introduction to the main video. Note that things might go wrong if
the video sizes and codecs do not align perfectly. (TODO: does this
work as expected?)
```yaml
- output: output.mp4
editlist:
- input: intro.mkv
- start: 00:00
- stop: 99:00
- input: main.mkv
- start: 0:00
- stop: 99:00
- input: outro.mkv
- start: 0:00
- stop: 99:00
```
## See also
* https://trac.ffmpeg.org/wiki/Concatenate
* https://stackoverflow.com/q/7333232
* Inspired by
https://github.com/mvdoc/budapest-fmri-data/blob/master/scripts/preprocessing-stimulus/split_movie.sh
* mpv (https://mpv.io/) is a video player with good command line
interface, keyboard shortcuts, and scriptable so that you can make a
hotkey that copies the current time.
* script for the mpv video player, which can copy the time when you
push a button. Might need some modification:
https://github.com/Kr4is/mpv-copy-time
* `[` and `]` change the playback speed. `O` causes time to be
permanently shown. `→` and `←` seek, `↑` and `↓` seek longer, and
`--hr-seek` allows seeking exactly. `Control+→`, `Control+←`
allow seeking to the next/previous subtitle.
## Status / Contributing
Alpha/beta, under development, it is starting to become reusable but
still development is for a few use cases. In order to use this you
probably have to read some code / work around some bugs since it isn't
well tested yet.
Bug reports or improvements welcome, but it is kind of a mess now.
Test with ``pytest ffmpeg-editlist.py``, but note that main
functionality is not tested right now.
Raw data
{
"_id": null,
"home_page": "",
"name": "ffmpeg-editlist",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Richard Darst",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/12/48/ae5cc43122841a0e84f75fe121bafc5d10b000b36d5facf503f15228af15/ffmpeg_editlist-0.5.4.tar.gz",
"platform": null,
"description": "# ffmpeg editlist utility\n\nOften, one wants to reprocess a video file using some basic\noperations, such as removing certain segments. Rather than opening a\nvideo editor, it is nice to be able to define a text file (the\n**editlist**) with processing instructions, and then run it. This\nallows collaboration in the processing, for example sharing the\neditlist file via git.\n\nThis utility takes a YAML definition of an editlist (segments to cut\nout and re-assemble into a file), and does the re-assembling using the\nffmpeg command line utility.\n\nThis is currently an alpha-level utility: it works, but expect it may\nnot exactly fit your use case without a bit of work. Documentation is\nminimal but still needs improvement. However, it has been used for\nseveral large events.\n\nVideo demonstration: https://youtu.be/thvMNTBJg2Y\n\nFeatures include:\n\n* YAML edit list definition.\n* Select segments to stitch together in the final video file.\n Segments are either copied raw or re-encoded (`--reencode`).\n* Give Table of Contents times (for example, '16:45: Lesson 2 begins')\n relative to the source video, output mapped to times in\n the output video automatically.\n* Cover certain areas of video (for example, when an audience member\n appears).\n* Everything scripted and non-interactive.\n* Cutting and re-splicing subtitles, too.\n\n\n\n## Installation and dependencies\n\nThis is on PyPI, may be installed with `pip install ffmpeg-editlist`.\nThe only dependency is PyYAML so it might be reasonable to install\nwith `pip install --user`. This creates a `ffmpeg-editlist` command\nin your environment.\n\nFor usage without installing, `ffmpeg_editlist.py` works as\nstand-alone with only `pyyaml`.\n\nIt depends on the `ffmpeg` command line utility, which must be\ninstalled through the operating system. Version requirements of\n`ffmpeg` are currently unknown.\n\n\n\n## Usage\n\nStart with a directory of your videos (example: `day1-raw.mkv`).\n\nCreate an edit list file (described in next section). A minimal\nexample is:\n\n```yaml\n- input: day1-raw.mkv\n\n- output: part1.mkv\n title: This is the title of part1\n description: >-\n This is the multi-line description\n of part 1.\n editlist:\n - start: 00:00 # These are time segments to include\n - 4:00: Begin exercise 1\n - stop: 5:00\n - start: 6:13\n - -: Going over the exercises # '-' means \"latest start time\".\n - stop: 99:00\n```\n\nThe general usage is then:\n\n```\npython ffmpeg-editlist.py EDITLIST.yaml INPUT-DIR [-o OUTPUT-DIR]\n```\n\nWhere `INPUT-DIR` is the search path for input files and `OUTPUT-DIR`\n(default `.`) is the output path for files. You can use the `--limit\nPATTERN` option to reprocess only a few videos (example: `--limit\npart1`).\n\nBecause of the way keyframes work, there may be missing segments\naround the transition points. After you have tested that your timings\nseem reasonable, re-run with ``--reencode`` and it will do a full\nre-encoding and make a seamless videos. The default encoding settings\nare designed to be slow but good enough for all practical purposes:\n\n```\npython ffmpeg-editlist.py EDITLIST.yaml --reencode INPUT-DIR [-o OUTPUT-DIR]\n```\n\n`OUTPUT-DIR` will get the encoded files, and `.txt` files with the\nvideo descriptions ready to upload to your video hosting site.\n\nSubtitles: The option `--srt` will make ffmpeg-editlist reprocess\nsubtitles just like video segments (cut to the segments and adjust\ntimestamps). A `.srt` file is expected alongside each input file\n(input file's extension replaced with `.srt`), and an output is\nsimilarly placed alongside each output. Warning: make sure that no\nsegment's declared stop time goes beyond the actual file length. It's\npossible that there will be some weird effects around the\nbeginning/end of the segments if subtitles go beyond the start/stop.\n\n\n\n## Editlist definition\n\n\n### Minimal example: single file\n\n```yaml\n# Input is taken from command line argument `input`.\n- output: output.mp4\n title: This is the title\n description: >-\n This is the multi-line description.\n editlist:\n - start: 00:00 # These are time segments to include\n - stop: 5:00\n - start: 6:13\n - stop: 99:00\n```\n\nRun with `python ffmpeg-editlist.py editlist.yaml input.mkv`.\n\n\n### Minimal example with multiple files\n\n```yaml\n\n- input: raw-day1.mkv\n output: day1-part1.mkv\n editlist:\n - start: 1:12\n - stop: 55:30\n\n# Previous input file is used if no new input is defined\n- output: day1-part2.mkv\n editlist:\n - start: 1:00:12\n - stop: 1:54:00\n```\n\nRun with `python ffmpeg-editlist.py editlist.yaml $input_directory`.\n\n\n### Multi-file with video descriptions\n\nThis is a full example that demonstrates all features.\n\n```yaml\n\n- workshop_description: >\n If this exists, it will be appended to the bottom of every video\n description. For example, it can be general information about the\n overall workshop.\n\n# This input will be used for all segments until redefined\n# Input relative to the input-dir command line argument.\n# If not given, use the raw input-dir argument as a filename.\n- input: cr-2021may-day1-obs.mov\n\n# A basic example\n# Output is relative to the output-dir command line argument.\n- output: day1-welcome.mp4\n # If given, do not reencode this segment even if --reencode is given\n # (useful for segments that start at 00:00). 'reencode: true' does\n # nothing, this is the default and --reencode must still be\n # specified on the command line.\n #reencode: false\n editlist:\n - start: 12:20\n - stop: 31:14\n\n# Git-intro day 1\n- output: day1-git-intro-1.mp4 # Output filename\n title: YouTube Video Title\n description: >\n Description of the video.\n editlist:\n # These pairs are times to *include*\n - start: 31:14\n - stop: 38:13\n - start: 41:28\n - stop: 1:04:45\n\n# A sample including table of contents entries.\n# You need to map times from the raw file, to the output file, in\n# order to make a clickable YouTube table of contents.\n# They are times in the\n# original video, and they are converted to the equivalent times in\n# the processed videos. They must be within the ranges above (and\n# you get a unhandled error if they aren't):\n# segment_start <= toc_time < segment_stop.\n# These can be interspersed with the segment definitions.\n# Example:\n- output: day2-git-intro-2.mp4\n editlist:\n - start: 31:14\n # TOC entry:\n - 31:14: Overview of the day\n - 33:25: Motivation to version control\n - stop: 38:13\n - start: 41:28\n - -: Basics of version control # '-' is an alias for \"last start\"\n - 48:35: \"Exercise: record changes\" # has a ':', so must be quoted\n - stop: 1:04:45\n #- 1:18:22: This will fail, timestamp after the end\n\nThis syntax is used to cover a segment of the video:\n- output: day3-has-audience-visible.mp4\n editlist:\n - start: 00:00\n # Cover an area. begin/end are clear. w and h are width and\n # height. x and y are offset (left, down) from the top-left corner\n - cover: {begin: \"1:15:29\", end: \"1:51:34\", w: 840, h: 300, x: 360}\n - stop: 5:00\n\n\n```\n\nAlongside the `.mp4` output file, a `.mp4.info.txt` file is created\nwith these contents. This is designed for easy copying and pasting\ninto hosting sites:\n\n```\nTitle of Video\n\nVideo description.\n\n01:53 Table of contents entry 1\n15:45 Table of contents entry 2\n...\n\n\nWorkshop description.\n```\n\n\n### Multiple inputs\n\nMultiple inputs in one segment might be useful when you are attaching\nan introduction to the main video. Note that things might go wrong if\nthe video sizes and codecs do not align perfectly. (TODO: does this\nwork as expected?)\n\n```yaml\n- output: output.mp4\n editlist:\n - input: intro.mkv\n - start: 00:00\n - stop: 99:00\n - input: main.mkv\n - start: 0:00\n - stop: 99:00\n - input: outro.mkv\n - start: 0:00\n - stop: 99:00\n\n```\n\n\n\n## See also\n\n* https://trac.ffmpeg.org/wiki/Concatenate\n* https://stackoverflow.com/q/7333232\n* Inspired by\n https://github.com/mvdoc/budapest-fmri-data/blob/master/scripts/preprocessing-stimulus/split_movie.sh\n* mpv (https://mpv.io/) is a video player with good command line\n interface, keyboard shortcuts, and scriptable so that you can make a\n hotkey that copies the current time.\n * script for the mpv video player, which can copy the time when you\n push a button. Might need some modification:\n https://github.com/Kr4is/mpv-copy-time\n * `[` and `]` change the playback speed. `O` causes time to be\n permanently shown. `\u2192` and `\u2190` seek, `\u2191` and `\u2193` seek longer, and\n `--hr-seek` allows seeking exactly. `Control+\u2192`, `Control+\u2190`\n allow seeking to the next/previous subtitle.\n\n\n## Status / Contributing\n\nAlpha/beta, under development, it is starting to become reusable but\nstill development is for a few use cases. In order to use this you\nprobably have to read some code / work around some bugs since it isn't\nwell tested yet.\n\nBug reports or improvements welcome, but it is kind of a mess now.\nTest with ``pytest ffmpeg-editlist.py``, but note that main\nfunctionality is not tested right now.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Cut and splice video files using a YAML definition file and ffmpeg",
"version": "0.5.4",
"project_urls": {
"Home": "https://github.com/coderefinery/ffmpeg-editlist/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ebbbf1a40532f017c73f32ae20e6b40e31a55d743aca1578722ec450c807a451",
"md5": "59da2923227c37b497130be2d1e94c43",
"sha256": "51d4295aeac0697ede5e5c9c55e101d2a2618c5075ede8b37567806462776117"
},
"downloads": -1,
"filename": "ffmpeg_editlist-0.5.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "59da2923227c37b497130be2d1e94c43",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12062,
"upload_time": "2024-01-18T22:46:27",
"upload_time_iso_8601": "2024-01-18T22:46:27.974290Z",
"url": "https://files.pythonhosted.org/packages/eb/bb/f1a40532f017c73f32ae20e6b40e31a55d743aca1578722ec450c807a451/ffmpeg_editlist-0.5.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1248ae5cc43122841a0e84f75fe121bafc5d10b000b36d5facf503f15228af15",
"md5": "3930cc29fc9ab006c8b8764412ad6ac8",
"sha256": "291849a617c5e27d536a09a6306aa2b445feedd22720504535ae16579c5933d1"
},
"downloads": -1,
"filename": "ffmpeg_editlist-0.5.4.tar.gz",
"has_sig": false,
"md5_digest": "3930cc29fc9ab006c8b8764412ad6ac8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 401074,
"upload_time": "2024-01-18T22:46:29",
"upload_time_iso_8601": "2024-01-18T22:46:29.486890Z",
"url": "https://files.pythonhosted.org/packages/12/48/ae5cc43122841a0e84f75fe121bafc5d10b000b36d5facf503f15228af15/ffmpeg_editlist-0.5.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-18 22:46:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "coderefinery",
"github_project": "ffmpeg-editlist",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "ffmpeg-editlist"
}
