From 134ea56b8806585d3997c1ea13d9c6d4ce468140 Mon Sep 17 00:00:00 2001 From: Joshua Minor Date: Fri, 15 Aug 2025 11:15:52 -0700 Subject: [PATCH 1/9] Update otiotool usage & argument validation Signed-off-by: Joshua Minor --- .../opentimelineio/console/otiotool.py | 43 +++++++++---------- 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/src/py-opentimelineio/opentimelineio/console/otiotool.py b/src/py-opentimelineio/opentimelineio/console/otiotool.py index aca4bf1e5..6d3c7eb51 100755 --- a/src/py-opentimelineio/opentimelineio/console/otiotool.py +++ b/src/py-opentimelineio/opentimelineio/console/otiotool.py @@ -193,29 +193,31 @@ def parse_arguments(): the filtering options provided are passed to the next phase. 3. Combine - If specified, the --stack, --concat, and --flatten operations are + If specified, the --stack, or --concat operations are performed (in that order) to combine all of the input timeline(s) into one. -4. Relink +4. Flatten + If --flatten is specified, then multiple tracks are flattened into one. + +5. Relink The --relink-by-name option, will scan the specified folder(s) looking for files which match the name of each clip in the input timeline(s). If matching files are found, clips will be relinked to those files (using file:// URLs). Clip names are matched to filenames ignoring file extension. If specified, the --copy-media-to-folder option, will copy or download all linked media, and relink the OTIO to reference the local copies. - -5. Remove/Redact +6. Remove/Redact The --remove-metadata-key option allows you to remove a specific piece of metadata from all objects. If specified, the --redact option, will remove ALL metadata and rename all objects in the OTIO with generic names (e.g. "Track 1", "Clip 17", etc.) -6. Inspect +7. Inspect Options such as --stats, --list-clips, --list-tracks, --list-media, --verify-media, --list-markers, --verify-ranges, and --inspect will examine the OTIO and print information to standard output. -7. Output +8. Output Finally, if the "--output " option is specified, the resulting OTIO will be written to the specified file. The extension of the output filename is used to determine the format of the output (e.g. OTIO or any @@ -251,18 +253,20 @@ def parse_arguments(): ) # Filter... - parser.add_argument( + track_type_group = parser.add_mutually_exclusive_group() + track_type_group.add_argument( "--video-only", "-v", action='store_true', help="Output only video tracks" ) - parser.add_argument( + track_type_group.add_argument( "--audio-only", "-a", action='store_true', help="Output only audio tracks" ) + parser.add_argument( "--only-tracks-with-name", type=str, @@ -328,13 +332,15 @@ def parse_arguments(): help="""When used with --flatten, the new flat track is added above the others instead of replacing them.""" ) - parser.add_argument( + + combine_group = parser.add_mutually_exclusive_group() + combine_group.add_argument( "--stack", "-s", action='store_true', help="Stack multiple input files into one timeline" ) - parser.add_argument( + combine_group.add_argument( "--concat", "-c", action='store_true', @@ -342,7 +348,8 @@ def parse_arguments(): ) # Relink - parser.add_argument( + relink_group = parser.add_mutually_exclusive_group() + relink_group.add_argument( "--relink-by-name", type=str, nargs='+', @@ -350,7 +357,7 @@ def parse_arguments(): help="""Scan the specified folder looking for filenames which match each clip's name. If found, clips are relinked to those files.""" ) - parser.add_argument( + relink_group.add_argument( "--copy-media-to-folder", type=str, metavar='FOLDER', @@ -457,20 +464,10 @@ def parse_arguments(): if not any([args.input, args.list_versions]): parser.error("Must specify at least one of --input or --list-versions.") - # Some options cannot be combined. - - if args.video_only and args.audio_only: - parser.error("Cannot use --video-only and --audio-only at the same time.") - - if args.stack and args.concat: - parser.error("Cannot use --stack and --concat at the same time.") - + # Check some options combination. if args.keep_flattened_tracks and not args.flatten: parser.error("Cannot use --keep-flattened-tracks without also using --flatten.") - if args.input and args.list_versions: - parser.error("Cannot combine --input and --list-versions.") - return args From 9c2c8bcb1ff9e332f69ada1461b25c1e6981050e Mon Sep 17 00:00:00 2001 From: Joshua Minor Date: Fri, 15 Aug 2025 11:16:00 -0700 Subject: [PATCH 2/9] Added otiotool tutorial Signed-off-by: Joshua Minor --- docs/tutorials/otiotool.md | 304 +++++++++++++++++++++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 docs/tutorials/otiotool.md diff --git a/docs/tutorials/otiotool.md b/docs/tutorials/otiotool.md new file mode 100644 index 000000000..fc39457a9 --- /dev/null +++ b/docs/tutorials/otiotool.md @@ -0,0 +1,304 @@ +# otiotool Tutorial + +`otiotool` is a command-line utility in OpenTimelineIO for inspecting, manipulating, and transforming OTIO timeline files. This tutorial covers its main features and usage patterns, with practical examples. + +## Installation + +`otiotool` is included with several other command line utilities as part of the +OpenTimelineIO Python module. You can install it via typical Python utilities +like `pip`, etc. + +If you don't already have that module installed, but you do have +[uv installed](https://docs.astral.sh/uv/), then you can use `otiotool` with +this handy shortcut: + +```bash +uvx --from opentimelineio otiotool +``` + +## Basic Usage + +`otiotool` reads one or more OTIO timeline files, optionally makes changes to the timelines, and outputs a text report and/or a new OTIO file with the result. + +To run `otiotool` for reporting, use: + +```bash +otiotool --input [more inputs...] [options] +``` + +To run `otiotool` to create a new OTIO file, use: + +```bash +otiotool --input [more inputs...] [options] --output +``` + +Many of `otiotool`'s command line options have a long and a short form. For example: `--input` is also `-i`, and `--output` is `-o`. + +For a complete listing of all options use `otiotool -h`. + +## Phases + +Unlike some other command line tools, the order in which options appear on +the command line does not matter. For example `otiotool -i input.otio --flatten -o output.otio` is the same as `otiotool --flatten -o output.otio -i input.otio` +Instead, the features of this tool work in phases, as follows: + +1. Input + Input files provided by the `--input ` argument(s) are read into + memory. Files may be OTIO format, or any format supported by adapter + plugins. + +2. Filtering + Options such as `--video-only`, `--audio-only`, `--only-tracks-with-name`, + `--only-tracks-with-index`, `--only-clips-with-name`, + `--only-clips-with-name-regex`, `--remove-transitions`, and `--trim` will remove + content. Only the tracks, clips, etc. that pass all of the filtering options + provided are passed to the next phase. + +3. Combine + If specified, the `--stack` or `--concat` operations are + performed (in that order) to combine all of the input timeline(s) into one. + +4. Flatten + If `--flatten` is specified, multiple tracks are flattened into one. + +5. Relink + The `--relink-by-name` option, will scan the specified folder(s) looking for + files which match the name of each clip in the input timeline(s). + If matching files are found, clips will be relinked to those files (using + file:// URLs). Clip names are matched to filenames ignoring file extension. + If specified, the `--copy-media-to-folder` option, will copy or download + all linked media, and relink the OTIO to reference the local copies. + +6. Remove/Redact + The `--remove-metadata-key` option allows you to remove a specific piece of + metadata from all objects. + If specified, the `--redact` option, will remove ALL metadata and rename all + objects in the OTIO with generic names (e.g. "Track 1", "Clip 17", etc.) + +7. Inspect + Options such as `--stats`, `--list-clips`, `--list-tracks`, `--list-media`, + `--verify-media`, `--list-markers`, `--verify-ranges`, and `--inspect` + will examine the OTIO and print information to standard output. + +8. Output + Finally, if the `--output ` option is specified, the resulting + OTIO will be written to the specified file. The extension of the output + filename is used to determine the format of the output (e.g. OTIO or any + format supported by the adapter plugins.) If you need to output an older + schema version, see the `--downgrade` option. + + +## Listing Timeline Contents + +### List Tracks +Prints all tracks in the timeline: +```bash +otiotool -i multitrack.otio --list-tracks +``` +Output: +``` +TIMELINE: OTIO TEST - multitrack.Exported.01 +TRACK: Sequence (Video) +TRACK: Sequence 2 (Video) +TRACK: Sequence 3 (Video) +``` + +### List Clips, Markers, etc. +Prints all clips and markers in the timeline: +```bash +otiotool -i screening_example.otio --list-clips --list-markers +``` +Output: +``` +TIMELINE: Example_Screening.01 + CLIP: ZZ100_501 (LAY3) + CLIP: ZZ100_502A (LAY3) + CLIP: ZZ100_503A (LAY1) + CLIP: ZZ100_504C (LAY1) + MARKER: global: 00:59:49:13 local: 01:00:01:14 duration: 0.0 color: RED name: ANIM FIX NEEDED + MARKER: global: 00:59:50:13 local: 01:00:02:14 duration: 0.0 color: PINK + ... +``` + +## Filtering Tracks and Clips + +### Video or Audio Only +List only video or audio clips: +```bash +otiotool -i premiere_example.otio --video-only --list-clips +otiotool -i premiere_example.otio --audio-only --list-clips +``` + +### Filter by Track Name or Index +```bash +otiotool -i multitrack.otio --only-tracks-with-name "Sequence 3" --list-clips +otiotool -i multitrack.otio --only-tracks-with-index 3 --list-clips +``` + +Note that indexes for `--only-tracks-with-index` begin at 1 for the first track, and that you often want to use it in combination with `--video-only` or `--audio-only`. + +### Filter Clips by Name or Regex +```bash +otiotool -i premiere_example.otio --list-clips --only-clips-with-name "sc01_sh010_anim.mov" +otiotool -i premiere_example.otio --list-clips --only-clips-with-name-regex "sh\d+_anim" +``` + +Note that `--only-clips-with-name-regex` uses the Regular Expression syntax [documented here](https://docs.python.org/3/library/re.html). + +## Media Information + +### List Media References +```bash +otiotool -i multitrack.otio --list-tracks --list-clips --list-media +``` + +### Verify Media Existence +Checks if media files exist. Note, only local file paths are checked by `otiotool` not URLs or other non-file path media references. +```bash +otiotool -i premiere_example.otio --verify-media +``` + +## Statistics and Inspection + +### Print Timeline Stats +```bash +otiotool -i multitrack.otio --stats +``` +Output: +``` +Name: OTIO TEST - multitrack.Exported.01 +Start: 00:00:00:00 +End: 00:02:16:18 +Duration: 00:02:16:18 +``` + +### Inspect Items +Show details for a specific item: +```bash +otiotool -i multitrack.otio --inspect "KOLL" +``` +Output: +``` +TIMELINE: OTIO TEST - multitrack.Exported.01 + ITEM: KOLL-HD.mp4 () + source_range: TimeRange(RationalTime(0, 24), RationalTime(640, 24)) + trimmed_range: TimeRange(RationalTime(0, 24), RationalTime(640, 24)) + visible_range: TimeRange(RationalTime(0, 24), RationalTime(640, 24)) + range_in_parent: TimeRange(RationalTime(1198, 24), RationalTime(640, 24)) + trimmed range in timeline: TimeRange(RationalTime(1198, 24), RationalTime(640, 24)) + visible range in timeline: TimeRange(RationalTime(1198, 24), RationalTime(640, 24)) + range in Sequence 3 (): TimeRange(RationalTime(1198, 24), RationalTime(640, 24)) + range in NestedScope (): TimeRange(RationalTime(1198, 24), RationalTime(640, 24)) +``` + + +## Output File + +Modifications to the timeline(s) can be written out to a new file with the +`--output ` option. + +### Multiple Timelines + +If the result is a single timeline, then resulting file contains that timeline +as expected. However, if there were multiple input files and those timelines +were not combined with `--concat` or `--stack` then the output will be a single +file containing a SerializableCollection with multiple timelines. This is a +supported OTIO feature, but many tools and workflows expect only a single +timeline in an OTIO file. + +### Standard In/Out + +If you specify the `--output` file as a single `-` then the resulting OTIO will +be written to as text to stdout instead of a file. You can also use `-` as an +input file. This allows you to chain `otiotool` with other tools on the command +line. + +```bash +otiotool -i multitrack.otio --video-only -o - | grep MissingReference +``` + +### Format Conversion + +The format of the output file is inferred +from the filename extension. It can be `.otio` for an OTIO file, or any other +file format supported by an available OTIO adapter plugin. Thus `otiotool` +can operate much like `otioconvert` however some more advanced conversion +options are only available in `otioconvert`. If you need both, you can write +to an intermediate OTIO file and convert to/from the other format in a separate +step. + +```bash +otiotool -i multitrack.otio --flatten video --video-only -o single-track.otio +``` + +Combined with conversion to EDL (via [this adapter plugin](https://github.com/OpenTimelineIO/otio-cmx3600-adapter)): +```bash +uvx --from opentimelineio --with otio-cmx3600-adapter otiotool -i multitrack.otio --flatten video --video-only -o single-track.edl +``` + +## Timeline Manipulation + +### Trim Timeline +Trim to a time range: +```bash +otiotool -i multitrack.otio --trim 20.5 40 -o output.otio +otiotool -i multitrack.otio --trim 00:01:00:00 00:02:00:00 -o output.otio +``` + +The start and end times for `--trim` can be either a floating point number of seconds +or timecode `HH:MM:SS:FF` in the frame rate inferred from the timeline itself. + +### Flatten Tracks +Combine tracks into one: +```bash +otiotool -i multitrack.otio --flatten video -o output.otio --list-tracks +``` + +### Stack or Concatenate Timelines +Stack multiple timelines: +```bash +otiotool -i multitrack.otio premiere_example.otio --stack -o output.otio --list-tracks +``` +Concatenate timelines end-to-end: +```bash +otiotool -i multitrack.otio premiere_example.otio --concat -o output.otio --stats +``` + +### Redact Timeline +Replace names of clips, tracks, etc. with generic labels: +```bash +otiotool -i multitrack.otio --redact -o output.otio --list-clips +``` + +### Remove Transitions +Remove all transitions: +```bash +otiotool -i transition.otio --remove-transitions -o output.otio +``` + +## OTIO Schema Versions + +When `otiotool` reads an older OTIO format, it will automatically upgrade +the file to the newest schema supported by `otiotool`. + +When working with an application or workflow that requires an older OTIO +file format, you can use `otiotool` to downgrade an OTIO to a specific schema +version which is compatible. + +See [Versioning Schemas](versioning-schemas.md) to understand this in detail. + +```bash +otiotool --list-versions +``` +Output: +``` +Available versions for --downgrade FAMILY:VERSION + OTIO_CORE:0.14.0 + OTIO_CORE:0.15.0 + OTIO_CORE:0.16.0 + OTIO_CORE:0.17.0 +``` + +```bash +otiotool -i multitrack.otio --downgrade OTIO_CORE:0.14.0 -o old-format.otio +``` From 2da24d2eba120ab1a7e51a0134de35575e48d79c Mon Sep 17 00:00:00 2001 From: Joshua Minor Date: Fri, 15 Aug 2025 11:26:38 -0700 Subject: [PATCH 3/9] Added otiotool tutorial to doc index Signed-off-by: Joshua Minor --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index fe6e8e64f..f8fcf55b9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,6 +28,7 @@ Quick Start tutorials/quickstart tutorials/otio-env-variables + tutorials/otiotool Tutorials ------------ From 71f0e394c075c889bf06f9bdc681f75ba9a3fd92 Mon Sep 17 00:00:00 2001 From: Joshua Minor Date: Fri, 15 Aug 2025 12:54:37 -0700 Subject: [PATCH 4/9] Addressed review notes, fixed formatting & relative links. Signed-off-by: Joshua Minor --- docs/tutorials/otiotool.md | 87 +++++++++++++++++++++++++++++++------- 1 file changed, 71 insertions(+), 16 deletions(-) diff --git a/docs/tutorials/otiotool.md b/docs/tutorials/otiotool.md index fc39457a9..376eaea18 100644 --- a/docs/tutorials/otiotool.md +++ b/docs/tutorials/otiotool.md @@ -6,11 +6,11 @@ `otiotool` is included with several other command line utilities as part of the OpenTimelineIO Python module. You can install it via typical Python utilities -like `pip`, etc. +like `pip`, etc. See [Quickstart](./quickstart#install-otio]) for details. -If you don't already have that module installed, but you do have +[!NOTE] If you have [uv installed](https://docs.astral.sh/uv/), then you can use `otiotool` with -this handy shortcut: +this handy shortcut without having to deal with any installation: ```bash uvx --from opentimelineio otiotool @@ -20,12 +20,20 @@ uvx --from opentimelineio otiotool `otiotool` reads one or more OTIO timeline files, optionally makes changes to the timelines, and outputs a text report and/or a new OTIO file with the result. -To run `otiotool` for reporting, use: +To run `otiotool` for reporting, use options like `--list-clips` or `--list-tracks`. The report output is +printed to the console: ```bash otiotool --input [more inputs...] [options] ``` +Report output can be redirected from standard output +to a file like any terminal program: + +```bash +otiotool --input [more inputs...] [options] > report.txt +``` + To run `otiotool` to create a new OTIO file, use: ```bash @@ -34,20 +42,37 @@ otiotool --input [more inputs...] [options] --output report.txt +``` + For a complete listing of all options use `otiotool -h`. ## Phases Unlike some other command line tools, the order in which options appear on -the command line does not matter. For example `otiotool -i input.otio --flatten -o output.otio` is the same as `otiotool --flatten -o output.otio -i input.otio` +the command line does not matter. For example these two commands do the same thing: + +```bash +otiotool -i input.otio --flatten -o output.otio +otiotool --flatten -o output.otio -i input.otio +``` + Instead, the features of this tool work in phases, as follows: 1. Input + Input files provided by the `--input ` argument(s) are read into memory. Files may be OTIO format, or any format supported by adapter plugins. 2. Filtering + Options such as `--video-only`, `--audio-only`, `--only-tracks-with-name`, `--only-tracks-with-index`, `--only-clips-with-name`, `--only-clips-with-name-regex`, `--remove-transitions`, and `--trim` will remove @@ -55,13 +80,16 @@ Instead, the features of this tool work in phases, as follows: provided are passed to the next phase. 3. Combine + If specified, the `--stack` or `--concat` operations are performed (in that order) to combine all of the input timeline(s) into one. 4. Flatten + If `--flatten` is specified, multiple tracks are flattened into one. 5. Relink + The `--relink-by-name` option, will scan the specified folder(s) looking for files which match the name of each clip in the input timeline(s). If matching files are found, clips will be relinked to those files (using @@ -70,17 +98,20 @@ Instead, the features of this tool work in phases, as follows: all linked media, and relink the OTIO to reference the local copies. 6. Remove/Redact + The `--remove-metadata-key` option allows you to remove a specific piece of metadata from all objects. If specified, the `--redact` option, will remove ALL metadata and rename all objects in the OTIO with generic names (e.g. "Track 1", "Clip 17", etc.) 7. Inspect + Options such as `--stats`, `--list-clips`, `--list-tracks`, `--list-media`, `--verify-media`, `--list-markers`, `--verify-ranges`, and `--inspect` will examine the OTIO and print information to standard output. 8. Output + Finally, if the `--output ` option is specified, the resulting OTIO will be written to the specified file. The extension of the output filename is used to determine the format of the output (e.g. OTIO or any @@ -143,7 +174,7 @@ otiotool -i premiere_example.otio --list-clips --only-clips-with-name "sc01_sh01 otiotool -i premiere_example.otio --list-clips --only-clips-with-name-regex "sh\d+_anim" ``` -Note that `--only-clips-with-name-regex` uses the Regular Expression syntax [documented here](https://docs.python.org/3/library/re.html). +Note that `--only-clips-with-name-regex` uses the [Python Regular Expression syntax](https://docs.python.org/3/library/re.html). ## Media Information @@ -153,7 +184,7 @@ otiotool -i multitrack.otio --list-tracks --list-clips --list-media ``` ### Verify Media Existence -Checks if media files exist. Note, only local file paths are checked by `otiotool` not URLs or other non-file path media references. +Checks if media files exist. Note: only local file paths are checked by `otiotool`, not URLs or other non-file path media references. ```bash otiotool -i premiere_example.otio --verify-media ``` @@ -191,15 +222,29 @@ TIMELINE: OTIO TEST - multitrack.Exported.01 range in NestedScope (): TimeRange(RationalTime(1198, 24), RationalTime(640, 24)) ``` +## Input/Output + +### Input File(s) -## Output File +Multiple input files can be specified via `--input` like this: + +```bash +otiotool -i one.otio two.otio three.otio --concat -o result.otio +``` + +[!NOTE] When `otiotool` is given multiple inputs, the order of those inputs will affect the outcome of `--concat`, `--stack`, and any text reports printed to the console. + +### Output File Modifications to the timeline(s) can be written out to a new file with the `--output ` option. +Note: The input files are never modified unless the +output path specifies the same file, in which case that file will be overwritten (not recommended). + ### Multiple Timelines -If the result is a single timeline, then resulting file contains that timeline +If the result is a single timeline, then the output file will contain that timeline as expected. However, if there were multiple input files and those timelines were not combined with `--concat` or `--stack` then the output will be a single file containing a SerializableCollection with multiple timelines. This is a @@ -208,20 +253,30 @@ timeline in an OTIO file. ### Standard In/Out -If you specify the `--output` file as a single `-` then the resulting OTIO will -be written to as text to stdout instead of a file. You can also use `-` as an -input file. This allows you to chain `otiotool` with other tools on the command +You can chain `otiotool` with other tools on the command line. +If you specify the `--output` file as a single `-` then the resulting OTIO will +be printed as text to stdout instead of a file. + ```bash otiotool -i multitrack.otio --video-only -o - | grep MissingReference ``` +You can also use `-` as an +input from stdin. + +```bash +curl https://example.com/some/path/premiere_example.otio | otiotool -i - --verify-media --stats +``` + ### Format Conversion -The format of the output file is inferred +The format of the input and output file is inferred from the filename extension. It can be `.otio` for an OTIO file, or any other -file format supported by an available OTIO adapter plugin. Thus `otiotool` +file format supported by an available [OTIO adapter plugin](./adapters). + +Thus `otiotool` can operate much like `otioconvert` however some more advanced conversion options are only available in `otioconvert`. If you need both, you can write to an intermediate OTIO file and convert to/from the other format in a separate @@ -249,7 +304,7 @@ The start and end times for `--trim` can be either a floating point number of se or timecode `HH:MM:SS:FF` in the frame rate inferred from the timeline itself. ### Flatten Tracks -Combine tracks into one: +Combine multiple tracks into one with `--flatten ` where `TYPE` is either `video`, `audio`, or `all`: ```bash otiotool -i multitrack.otio --flatten video -o output.otio --list-tracks ``` @@ -285,7 +340,7 @@ When working with an application or workflow that requires an older OTIO file format, you can use `otiotool` to downgrade an OTIO to a specific schema version which is compatible. -See [Versioning Schemas](versioning-schemas.md) to understand this in detail. +See [Versioning Schemas](./versioning-schemas) to understand this in detail. ```bash otiotool --list-versions From 94baa9a1d27e1e156f261f397cf52d7f5ede8976 Mon Sep 17 00:00:00 2001 From: Joshua Minor Date: Fri, 15 Aug 2025 13:56:57 -0700 Subject: [PATCH 5/9] Use NOTE Markdown syntax Signed-off-by: Joshua Minor --- docs/tutorials/otiotool.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/otiotool.md b/docs/tutorials/otiotool.md index 376eaea18..cdf1c4fd4 100644 --- a/docs/tutorials/otiotool.md +++ b/docs/tutorials/otiotool.md @@ -166,7 +166,7 @@ otiotool -i multitrack.otio --only-tracks-with-name "Sequence 3" --list-clips otiotool -i multitrack.otio --only-tracks-with-index 3 --list-clips ``` -Note that indexes for `--only-tracks-with-index` begin at 1 for the first track, and that you often want to use it in combination with `--video-only` or `--audio-only`. +Indexes for `--only-tracks-with-index` begin at 1 for the first track, and that you often want to use it in combination with `--video-only` or `--audio-only`. ### Filter Clips by Name or Regex ```bash @@ -174,7 +174,7 @@ otiotool -i premiere_example.otio --list-clips --only-clips-with-name "sc01_sh01 otiotool -i premiere_example.otio --list-clips --only-clips-with-name-regex "sh\d+_anim" ``` -Note that `--only-clips-with-name-regex` uses the [Python Regular Expression syntax](https://docs.python.org/3/library/re.html). +The `--only-clips-with-name-regex` option uses the [Python Regular Expression syntax](https://docs.python.org/3/library/re.html). ## Media Information @@ -184,7 +184,7 @@ otiotool -i multitrack.otio --list-tracks --list-clips --list-media ``` ### Verify Media Existence -Checks if media files exist. Note: only local file paths are checked by `otiotool`, not URLs or other non-file path media references. +Checks if media files exist. Only local file paths are checked by `otiotool`, not URLs or other non-file path media references. ```bash otiotool -i premiere_example.otio --verify-media ``` @@ -239,7 +239,7 @@ otiotool -i one.otio two.otio three.otio --concat -o result.otio Modifications to the timeline(s) can be written out to a new file with the `--output ` option. -Note: The input files are never modified unless the +[!NOTE] The input files are never modified unless the output path specifies the same file, in which case that file will be overwritten (not recommended). ### Multiple Timelines From 387998919b3ae0a72952be3395606022c61e9504 Mon Sep 17 00:00:00 2001 From: Joshua Minor Date: Fri, 15 Aug 2025 13:57:51 -0700 Subject: [PATCH 6/9] More docs for --redact Signed-off-by: Joshua Minor --- docs/tutorials/otiotool.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/tutorials/otiotool.md b/docs/tutorials/otiotool.md index cdf1c4fd4..71721b518 100644 --- a/docs/tutorials/otiotool.md +++ b/docs/tutorials/otiotool.md @@ -324,6 +324,21 @@ Replace names of clips, tracks, etc. with generic labels: ```bash otiotool -i multitrack.otio --redact -o output.otio --list-clips ``` +Output: +``` +TIMELINE: Timeline #1 + CLIP: Clip #1 + CLIP: Clip #2 + CLIP: Clip #3 + CLIP: Clip #4 + CLIP: Clip #5 +``` + +This feature is meant for cases where you want to share an OTIO without leaking +sensitive information that might appear in a clip name, metadata, etc. For +example when filing a bug report. +Please look at the file contents after running this to ensure everything you +care about was handled. ### Remove Transitions Remove all transitions: From 578a0852b9d0ac37f467b8073665688bdd61746d Mon Sep 17 00:00:00 2001 From: Joshua Minor Date: Fri, 15 Aug 2025 13:58:56 -0700 Subject: [PATCH 7/9] Explain ordering of --stack and --concat Signed-off-by: Joshua Minor --- docs/tutorials/otiotool.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/otiotool.md b/docs/tutorials/otiotool.md index 71721b518..74da33800 100644 --- a/docs/tutorials/otiotool.md +++ b/docs/tutorials/otiotool.md @@ -310,13 +310,22 @@ otiotool -i multitrack.otio --flatten video -o output.otio --list-tracks ``` ### Stack or Concatenate Timelines -Stack multiple timelines: + +[!NOTE] With `--stack` and `--concat` the order of the input files affects the outcome. + +When concatenated, the inputs are assembled in the order listed, so the first input is earliest on the output timeline. + +Concat Example: ```bash -otiotool -i multitrack.otio premiere_example.otio --stack -o output.otio --list-tracks +otiotool -i opening.otio end_credits.otio --concat -o output.otio ``` -Concatenate timelines end-to-end: +``` + +When stacked, video tracks layer bottom-to-top, so the video tracks of the second input are layered above the first input. This follows conventional video/audio ordering where video tracks are layered numerically increasing upward (V2 is above V1). Audio tracks are layered in the opposite order, since traditionally audio tracks are layered numerically increasing downward (A2 is below A1). + +Stack Example: ```bash -otiotool -i multitrack.otio premiere_example.otio --concat -o output.otio --stats +otiotool -i a.otio b.otio --stack -o output.otio ``` ### Redact Timeline From e8e30442ecd055bfd429291a6d59ead5a43207d4 Mon Sep 17 00:00:00 2001 From: Joshua Minor Date: Mon, 18 Aug 2025 17:22:17 -0700 Subject: [PATCH 8/9] Fixed markdown syntax Signed-off-by: Joshua Minor --- docs/tutorials/otiotool.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/otiotool.md b/docs/tutorials/otiotool.md index 74da33800..7ae878cb3 100644 --- a/docs/tutorials/otiotool.md +++ b/docs/tutorials/otiotool.md @@ -6,9 +6,10 @@ `otiotool` is included with several other command line utilities as part of the OpenTimelineIO Python module. You can install it via typical Python utilities -like `pip`, etc. See [Quickstart](./quickstart#install-otio]) for details. +like `pip`, etc. See [Quickstart](./quickstart]) for details. -[!NOTE] If you have +> [!TIP] +> If you have [uv installed](https://docs.astral.sh/uv/), then you can use `otiotool` with this handy shortcut without having to deal with any installation: @@ -232,14 +233,16 @@ Multiple input files can be specified via `--input` like this: otiotool -i one.otio two.otio three.otio --concat -o result.otio ``` -[!NOTE] When `otiotool` is given multiple inputs, the order of those inputs will affect the outcome of `--concat`, `--stack`, and any text reports printed to the console. +> [!NOTE] +> When `otiotool` is given multiple inputs, the order of those inputs will affect the outcome of `--concat`, `--stack`, and any text reports printed to the console. ### Output File Modifications to the timeline(s) can be written out to a new file with the `--output ` option. -[!NOTE] The input files are never modified unless the +> [!NOTE] +> The input files are never modified unless the output path specifies the same file, in which case that file will be overwritten (not recommended). ### Multiple Timelines @@ -311,7 +314,8 @@ otiotool -i multitrack.otio --flatten video -o output.otio --list-tracks ### Stack or Concatenate Timelines -[!NOTE] With `--stack` and `--concat` the order of the input files affects the outcome. +> [!NOTE] +> With `--stack` and `--concat` the order of the input files affects the outcome. When concatenated, the inputs are assembled in the order listed, so the first input is earliest on the output timeline. From 1e2db8c3f52388ad3e5375a77d0a9c75c3aeea28 Mon Sep 17 00:00:00 2001 From: Joshua Minor Date: Tue, 19 Aug 2025 09:17:31 -0700 Subject: [PATCH 9/9] Fixed typo & clarified command line argument ordering Signed-off-by: Joshua Minor --- docs/tutorials/otiotool.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/otiotool.md b/docs/tutorials/otiotool.md index 7ae878cb3..d7b5e7641 100644 --- a/docs/tutorials/otiotool.md +++ b/docs/tutorials/otiotool.md @@ -6,7 +6,7 @@ `otiotool` is included with several other command line utilities as part of the OpenTimelineIO Python module. You can install it via typical Python utilities -like `pip`, etc. See [Quickstart](./quickstart]) for details. +like `pip`, etc. See [Quickstart](./quickstart) for details. > [!TIP] > If you have @@ -56,7 +56,7 @@ For a complete listing of all options use `otiotool -h`. ## Phases -Unlike some other command line tools, the order in which options appear on +Unlike some other command line tools, the order in which most options appear on the command line does not matter. For example these two commands do the same thing: ```bash @@ -64,6 +64,9 @@ otiotool -i input.otio --flatten -o output.otio otiotool --flatten -o output.otio -i input.otio ``` +The only time that command line argument ordering matters is when multiple input files are specified and operations like `--stack` and `--concat` combine them +together. + Instead, the features of this tool work in phases, as follows: 1. Input