transavormer/docs/STREAM-COMMANDS.md

Transform (transcode, transmux, etc) audio/video formats using libav.js and WebCodecs

Generally speaking, all TransAVormer streams are simply continuous,
beginning-to-end streams of their data. However, it is sometimes necessary to
change that behavior. For this purpose, TransAVormer supports *stream commands*,
which are commands that can be sent to alter the behavior of a stream.

To send stream commands, call the `sendCommands` method of your output stream
with an array of commands. Note that you should always call the final stream,
and not the stream most suited to receive the command; all streams will forward
commands backwards through the entire pipeline.

Stream commands have the following form:

```typescript
{
    c: string
}
```

The `c` field describes the command to be sent. Each command has additional
fields beyond this one, of course.

When an array of commands is sent, `sendCommands` returns an array of command
results, which have the following form:

```typescript
{
    c: string,
    ran: boolean,
    success: boolean,
    diagnostic: any[]
}
```

`ran` will be true if the command ran at all, i.e., if some element in the
pipeline was capable of interpreting and executing it. If `ran` is false, then,
perhaps counterintuitively, `success` is true—a command not being interpreted at
all is not considered a failure.

If the command was interpreted and executed but resulted in an error, then
`success` will be false. A diagnostic of some kind *may* be put in the
`diagnostic` array, but that is not guaranteed on failure.

The command results are actually added directly into the command objects, so all
parameters are present as well. For this reason, you should not reuse command
objects.

Each stream command is documented in a section below.


# Reselect

A reselect command changes the selection mapping for a packet selector or frame
selector. Note that it changes the *mapping*, but whether this can be usefully
interpreted by later components of the pipeline is your problem. If you change
the mapping such that a codec changes, or the number of streams changes, the
pipeline will fail spectacularly. Mind your maps.

A reselect command has the following form:

```typescript
{
    c: "reselect",
    selection: <same form as selector initializers>
}
```

The selection mapping is immediately updated based on the new selection.


# Seek

A seek command seeks in the input file, if possible. A seek command has the
following form:

```typescript
{
    c: "seek",
    time: number,
    min?: number,
    max?: number,
    stream?: number,
    streamTimebase?: boolean
}
```

The only mandatory field is `time`, the time to seek to, in seconds (by default,
but see `streamTimebase` below).

Seeking in most formats is inexact, both because data is discontinuous, and
because video data typically requires a keyframe. So, generally, you will seek
to *some time* before `time`, but exactly when depends on many circumstances.
You can set a floor on the time you seek to by additionally setting `min`.

Because the useful behavior of seeking is usually to get to some time *before*
`time`, `max` defaults to the same as `time`. If you set `max` to something
else, some formats are able to seek approximately and allow wiggle room in that
direction as well.

By default, seeking is supposed to choose which streams restrict its timing
wisely. You can instead override it to make these decisions based on a
particular stream, selected with `stream` by index.

All times default to seconds. If you set `streamTimebase` to true, they will
instead be interpreted in units of the timebase of the selected stream, or if no
stream is selected, in the default timebase of libav.js, microseconds.