class OnOutputConstraints

This event informs the client of new output constraints.

This message is ordered with respect to other output (such as output

packets, output format, output end-of-stream).

Before the first OnOutputPacket() of a stream, the server guarantees that

at least one OnOutputConstraints() and exactly one OnOutputFormat() will

be sent. The server may not set buffer_constraints_action_required true

in OnOutputConstraints() if the buffer config is already suitable for the

stream (buffer_constraints_action_required false means the buffer config

is already fine). The client must tolerate multiple

OnOutputConstraints() (and 1 OnOutputFormat() message) before the first

output packet. As long as the client hasn't moved to a new stream, the

server won't send another OnOutputConstraints() until after the client

has configured output buffers.

This message can be sent mid-stream by a server. If

buffer_constraints_action_required false, the message is safe to

ignore, but a client may choose to stash the new constraints for

later use the next time the client wants to unilaterally re-configure

buffers (when allowed). If later the server needs the output config to

change, the server may send a new OnOutputConstraints() with

buffer_constraints_action_required true.

On buffer_constraints_action_required true, a client that does not wish

to fully handle mid-stream output buffer config changes should either

give up completely on the processing, or at least re-config the output

as specified before starting a new stream (and possibly re-delivering

input data, if the client wants). This avoids useless retry with a new

stream starting from just before the output buffer config change which

would hit the same mid-stream output config change again.

Similarly, some servers may only partly support mid-stream format

changes, or only support a mid-stream format change if the buffers are

already large enough to handle both before and after the format change.

Such servers should still indicate buffer_constraints_action_required

true, but then send OnStreamFailed() after the client has re-configured

output buffers (seamlessly dealing with the mid-stream output config

change is even better of course, but is not always feasible depending on

format). When the client retries with a new stream starting from a

nearby location in the client's logical overall media timeline, the

output buffers will already be suitable for the larger size output, so

the new stream will not need any mid-stream output buffer re-config,

only a mid-stream OnOutputFormat(). This strategy avoids the problem

that would otherwise occur if a client were to retry with a new stream

starting just before the mid-stream output buffer config change (the

retry wouldn't be effective since the same need for an output buffer

config change would be hit again). Servers are discouraged from sending

OnStreamFailed() solely due to a mid-stream need for different output

buffer config without first sending OnOutputConstraints() with

buffer_constraints_action_required true and waiting for the client to

re-configure output buffers (to avoid the useless client retry with a

new stream from a logical location before the config change).

When buffer_constraints_action_required true, the server will not send

any OnOutputPacket() for this stream until after the client has

configured/re-configured output buffers.

A client that gives up on processing a stream on any mid-stream

OnOutputConstraints() or mid-stream OnOutputFormat() should completely

ignore any OnOutputConstraints() with buffer_constraints_action_required

false. Otherwise the client may needlessly fail processing, or server

implementations might not be able to use

buffer_constraints_action_required false for fear of simpler clients

just disconnecting.

All clients, even those which don't want to support any mid-stream

output buffer re-config or mid-stream OnOutputFormat() are required to

deal with 1..multiple OnOutputConstraints() messages before the first

output packet, and 1 OnOutputFormat() messages before the first output

packet.

This message is ordered with respect to output packets, and with respect

to OnOutputFormat().