Audio and multicam

Types

FadeableElement

interface FadeableElement {
  durationMs: number
  fadeInMs?: number | undefined
  fadeOutMs?: number | undefined
}

The duration and fade fields of an element that can carry audio fades.

ElementAudioSource

interface ElementAudioSource {
  elementId: ElementId
  assetId: AssetId
  asset: AssetRef
  timelineStartMs: number
  timelineDurationMs: number
  sourceStartMs: number
  sourceEndMs: number
  sourceSpanMs: number
  timeMap?: TimeMap
  reversed: boolean
}

The asset and source range a media clip plays audio from, with its timeline placement, time map, and reversal. For a multicam the asset is the audioSource source, and sourceStartMs is that source's offsetMs plus the multicam trimStartMs.

AngleCut

interface AngleCut {
  atMs: number
  layoutId: string
}

One entry in a multicam element's angle list, the source clock time a layout takes over and its layout id.

VisibleAngleCut

interface VisibleAngleCut {
  atMs: number
  localMs: number
  layoutId: string
}

An angle cut as it lands in a multicam's window, with its source clock time, its element-local position, and the layout that plays after it in playback order.

AngleTransitionWindow

interface AngleTransitionWindow {
  type: TransitionType
  durationMs: number
  cutMs: number
  fromLayoutId: string
  toLayoutId: string
}

A blend window around an angle cut, with the transition type, the clamped duration, the cut time on the source clock, and the layouts on each side.

FrameRequest

interface FrameRequest {
  assetId: string
  sourceTimeMs: number
}

One asset and the source time an element needs from it to paint a frame.

Functions

getEffectiveVolume

function getEffectiveVolume(element: TimelineElement, timelineMs: number): number

Returns the volume that plays at a timeline time, the animated or static volume scaled by the fade gain, or 0 for elements without a volume.

getFadeGain

function getFadeGain(element: FadeableElement, localMs: number): number

Returns the fade multiplier from 0 to 1 at an element-local time, ramping linearly over fadeInMs and fadeOutMs and taking the lower value where the ramps overlap.

hasFades

function hasFades(element: FadeableElement): boolean

Returns true when the element has a fade in or fade out longer than 0 ms.

getVoiceSource

function getVoiceSource(project: Project, element: TimelineElement): { assetId: AssetId; amount: number } | null

Returns the asset and mix amount for a clip whose voice cleanup is on and whose amount is above 0. Video and audio clips use their own asset. A multicam uses the asset of its audio source, the one resolveElementAudioSource returns. Returns null when voice is off, the amount is 0, or the asset is missing.

resolveElementAudioSource

function resolveElementAudioSource(
  project: Project,
  elementId: ElementId,
): ElementAudioSource | null

Returns the audio source of a video, audio, or multicam element, or null when the element, its asset, or the multicam audio source is missing. Every media clip resolves the same way, so trim, time map, and reversed apply to a multicam as they do to a video clip.

getActiveAngleIndex

function getActiveAngleIndex(angles: readonly AngleCut[], groupMs: number): number

Returns the index of the angle cut active at a source clock time, or 0 before the first cut.

getActiveLayout

function getActiveLayout(
  project: Project,
  element: MulticamElement,
  timelineMs: number,
): Layout | null

Returns the layout active in a multicam element at a timeline time, read on the source clock, or null when the layout id does not resolve.

getAngleTransitionAt

function getAngleTransitionAt(
  element: MulticamElement,
  groupMs: number,
): AngleTransitionWindow | null

Returns the angle transition window that contains a source clock time, where each window is centered on its cut and clamped so neighbors never overlap, or null.

getMulticamGroupTimeMs

function getMulticamGroupTimeMs(element: MulticamElement, timelineMs: number): number

Returns the source clock time a multicam plays at a timeline time. The source clock is the synced time every source shares, reached through the multicam's trim, time map, and reversal the way getSourceTimeMs reaches a video clip's media time.

getMulticamSourceTimeMs

function getMulticamSourceTimeMs(
  element: MulticamElement,
  source: MulticamSource,
  timelineMs: number,
): number

Returns the media time of one multicam source at a timeline time, its offsetMs plus the source clock time, clamped to 0 or more.

getVisibleAngleCuts

function getVisibleAngleCuts(element: MulticamElement): VisibleAngleCut[]

Returns the cuts a multicam plays, in playback order. The first entry is the layout open at local 0 and the rest are the cuts strictly inside the window, so each half of a split lists only its own cuts.

isAudioOnlySource

function isAudioOnlySource(project: Project, source: MulticamSource): boolean

Returns true when a multicam source's asset is audio. An audio-only source is never drawn and can be the multicam's audioSource.

getElementAssetIds

function getElementAssetIds(element: TimelineElement): AssetId[]

Returns the assets an element reads, its own asset for a video, audio, or image element, one per source for a multicam, and none for text or captions.

getFrameRequests

function getFrameRequests(
  project: Project,
  element: TimelineElement,
  timelineMs: number,
): FrameRequest[]

Returns the source frames an element needs at a timeline time, one request for a video or image, one per drawn source of the active layouts for a multicam element, and none for audio, text, or captions. Audio-only multicam sources never request a frame.