setDocument method

@override Future<void> setDocument(WaveformDocument document)

Swaps the document under an active session.

This method is the point of the whole playback path. A host can drag a trim handle or change a gain, and the user hears the result while playback continues.

The playhead keeps its position in the output timeline. Therefore, the sound continues from that position and does not jump. If a change makes the document shorter than the position of the playhead, the position clamps to the new end. A host that wants different behavior can seek directly afterwards.

This method is one call and not two, because both kinds of change cost the same work. The session rendered the queued frames ahead of the playhead through the old document, so those frames must go. The same is true of a gain change and of a trim.

Implementation

@override
Future<void> setDocument(WaveformDocument document) async {
  if (_disposed) throw StateError('This playback session was disposed.');

  documents.add(document);
  this.document = document;

  // The playhead keeps its output position and clamps to the new end, which
  // is what the real session does.
  if (_position > duration) _position = duration;
}