Discovering OTIO Adapter Arguments

adapter_arg_discovery.md

Discovering OTIO Adapter Arguments

Overview

The otioconvert program that ships with OpenTimelineIO has a handy feature that lets you pass arguments to adapters:

> otioconvert --help
...
  -a ADAPTER_ARG, --adapter-arg ADAPTER_ARG
                        Extra arguments to be passed to input adapter in the form of key=value. Values are strings, numbers or Python literals: True, False, etc. Can be used multiple times: -a
                        burrito="bar" -a taco=12. (default: [])
  -A OUTPUT_ADAPTER_ARG, --output-adapter-arg OUTPUT_ADAPTER_ARG
                        Extra arguments to be passed to output adapter in the form of key=value. Values are strings, numbers or Python literals: True, False, etc. Can be used multiple times:
                        -A burrito="bar" -A taco=12. (default: [])

As noted in the --help, these commandline arguments get passed into their respective adapters, letting you take advantage of those advanced features from the commandline. The question is, how do you know what those arguments are, and what they expect?

As an example, lets say that we wanted to downgrade a schema, but couldn't remember what the argument to the otio_json adapter was. How can we discover that?

OTIOPlugInfo

The command otiopluginfo also ships with OTIO, and provides information about the plugins installed on your system. If you run it, you'll probably get a gigantic wall of text, because by default it prints the information for all the plugins it finds, exhaustively.

Luckily, it has a number of flags you can set that help narrow it down for you:

> otiopluginfo --help
usage: otiopluginfo [-h] [-p {all,adapters,media_linkers,schemadefs,hook_scripts,hooks,version_manifests} [{all,adapters,media_linkers,schemadefs,hook_scripts,hooks,version_manifests} ...]]
                    [-a ATTRIBS [ATTRIBS ...]] [-l] [--version]
                    [plugpattern]

Print information about the OTIO plugin ecosystem.

positional arguments:
  plugpattern           Only print information about plugins that match this glob. (default: *)

optional arguments:
  -h, --help            show this help message and exit
  -p {all,adapters,media_linkers,schemadefs,hook_scripts,hooks,version_manifests} [{all,adapters,media_linkers,schemadefs,hook_scripts,hooks,version_manifests} ...], --plugin-types {all,adapters,media_linkers,schemadefs,hook_scripts,hooks,version_manifests} [{all,adapters,media_linkers,schemadefs,hook_scripts,hooks,version_manifests} ...]
                        Comma separated list of which kinds of plugins to print info on. (default: all)
  -a ATTRIBS [ATTRIBS ...], --attribs ATTRIBS [ATTRIBS ...]
                        Comma separated list of globs of which attributes to print info on. (default: ['*'])
  -l, --long-docs       Print full docstring instead of just the summary line. (default: False)
  --version             Print the otio and pkg_resource installed plugin version information to the commandline. (default: False)

We can use these flags to find the json adapter:

• we know that its an adapter, so the -p flag can limit to that type
• its probably got JSON in the name, so *json* probably will help

❯ otiopluginfo "*json*" -p adapters
Manifests loaded:
  ...

adapters:
  otio_json
    doc (short): Adapter for reading and writing native .otio json files.
    path: ...
    from manifest: ...
    explicit supported features:
      read_from_file args: ['filepath']
      read_from_string args: ['input_str']
      write_to_file args: ['input_otio', 'filepath', 'target_schema_versions', 'indent']
      write_to_string args: ['input_otio', 'target_schema_versions', 'indent']

And there it is! Putting it to use:

❯ otioconvert -i tests/sample_data/nested_example.otio -o /var/tmp/v14_compat.otio -A target_schema_versions="{'Clip':1}" && grep "OTIO_SCHEMA.*Clip" /var/tmp/v14_compat.otio
26:                        "OTIO_SCHEMA": "Clip.1",
75:                                "OTIO_SCHEMA": "Clip.1",
105:                        "OTIO_SCHEMA": "Clip.1",
162:                                "OTIO_SCHEMA": "Clip.1",
192:                        "OTIO_SCHEMA": "Clip.1",
249:                                "OTIO_SCHEMA": "Clip.1",
280:                        "OTIO_SCHEMA": "Clip.1",