fuchsia.audio

添加时间：HEAD

协议

DelayWatcher

在 fuchsia.audio/delay.fidl 中定义

留意延迟的变化。

WatchDelay

第一个调用会立即返回当前延迟（如果已知的话）。 后续调用会阻塞，直到延迟发生变化。最多只能有一个 未完成的通话，否则该频道可能会被关闭。

请求

名称类型
payload DelayWatcherWatchDelayRequest

响应

名称类型
payload DelayWatcherWatchDelayResponse

GainControl

在 fuchsia.audio/gain.fidl 中定义

支持控制和监控音频增益。该接口通常是 其他接口的剥离

旋钮

此接口公开了两个正交的旋钮：

  • 增益旋钮可控制“相对分贝”中的单个值。值为 0 表示无增益，正值会增加增益，负值 降低增益。根据上下文，可能会相对于 输入流或相对于某个绝对参考点（例如 扬声器的最大音量。

    此旋钮未定义最大值或最小值。个人 实现可能会限制实现定义的最大值或 将所有值低于实现定义的最低当量值 设为“静音”，但这不是必须的。

  • 静音旋钮控制单个布尔值。当 true 时， GainControl 被静音，并且有效增益为负无穷大。时间 false，增益由增益旋钮控制。

调度

您可以在增益和静音旋钮的调整时间 。调度在相对于参考时钟的时间戳上进行 必须在创建此协议时建立。

TODO(https://fxbug.dev/42176154)：调度语义可能会发生变化

SetGain

设置增益旋钮。

请求

名称类型
payload GainControlSetGainRequest

响应

名称类型
payload GainControl_SetGain_Result

SetMute

设置静音旋钮。

请求

名称类型
payload GainControlSetMuteRequest

响应

名称类型
payload GainControl_SetMute_Result

StreamSink

在 fuchsia.audio/stream_sink.fidl 中定义

用于跨进程音频流传输的数据包接收器，由音频使用者实现并用于 音频制作商

结束

表示已达到数据流结尾。音频渲染器等使用方 当流结束之前的最后一个数据包已呈现时，向客户端发送信号， 例如，客户端知道何时更改播放器的界面状态，让用户知道 播放完毕。此方法在逻辑上将作用域限定为当前片段。答 此请求之后可能会发出 SetSegment 请求和（通常）更多数据包。

请求

<空>

OnWillClose

在消费者关闭之前发送，说明消费者关闭 连接。发送此事件后，使用方必须避免再发送 消息并立即关闭连接。

响应

名称类型
payload StreamSinkOnWillCloseRequest

PutPacket

将数据包放入接收器。

请求

名称类型
payload StreamSinkPutPacketRequest

StartSegment

开始一个新细分。在此请求之后和下一个此类请求之前的数据包 分配给该细分受众群

请求

名称类型
payload StreamSinkStartSegmentRequest

WillClose

在生产方关闭前立即发送，指明生产方为何要关闭 连接。发送此请求后，提供方必须避免再发送 消息并立即关闭连接。

请求

名称类型
payload StreamSinkWillCloseRequest

结构体

UnspecifiedBestEffort

在 fuchsia.audio/stream_sink.fidl 中定义

<空>

UnspecifiedContinuous

在 fuchsia.audio/stream_sink.fidl 中定义

<空>

精英

ChannelConfig 柔性

类型：uint32

在 fuchsia.audio/format.fidl 中定义

频道的空间分配。

名称值说明
1

Front.C（中央）
2

前左（左）|前右（右）
3

Front.L |前右 |Back.L |Back.R，也称为“四个角”
4

Front.L |前右 |Back.C，也称为“LRS”
5

Front.L |前右 |Front.C |Back.C，也称为“LRCS”
6

Front.L |前右 |Front.C |LFE |Side.L |Side.R

CompressionType 柔性

类型：uint32

在 fuchsia.audio/compression.fidl 中定义

名称值说明
0
1
2
3
4
5
6
7
8
9
10
11
12
13

GainError 柔性环境

类型：uint32

在 fuchsia.audio/gain.fidl 中定义

GainControl 返回的错误类型。

名称值说明
1

未提供必填字段。
2

灵活字段包含不受支持的选项。如果存在这种情况， 使用 API 版本 X+1 构建的客户端与使用 API 构建的服务器通信 X 版。

SampleType 柔性环境

类型：uint32

在 fuchsia.audio/format.fidl 中定义

表示各个音频样本的类型。

名称值说明
1
2
3
4
5

表格

“Compression”（压缩）

在 fuchsia.audio/compression.fidl 中定义

描述应用于数据流的压缩。

Ordinal字段类型说明
type CompressionType

应用于音频流的压缩类型。
oob_parameters vector<uint8>[32768]

描述流压缩的不透明“带外”参数。此 此字段是 CompressionType 的函数。它会向解码器传递参数， 所需的资源许多压缩类型并不需要 此字段。

DelayWatcherWatchDelayRequest

在 fuchsia.audio/delay.fidl 中定义

Ordinal字段类型说明

DelayWatcherWatchDelayResponse

在 fuchsia.audio/delay.fidl 中定义

Ordinal字段类型说明
delay zx/Duration

可选。如果未指定，则延迟未知。

格式

在 fuchsia.audio/format.fidl 中定义

描述不考虑压缩的用于音频流的格式。地点 支持压缩，此类型应与 fuchsia.media2.Compression 结合使用。 未压缩的音频流使用 LPCM 编码。

Ordinal字段类型说明
sample_type SampleType

单个样本的类型。
channel_count uint32

每帧的样本数。
frames_per_second uint32

每秒帧数。
channel_layout ChannelLayout

每个声道的空间分配。

GainControlSetGainRequest

在 fuchsia.audio/gain.fidl 中定义

Ordinal字段类型说明
how GainUpdateMethod

如何更新增益旋钮。

必填。
when fuchsia.media2/RealTime

何时应用此更新。

必填。

GainControlSetMuteRequest

在 fuchsia.audio/gain.fidl 中定义

Ordinal字段类型说明
muted bool

静音旋钮的新值。

必填。
when fuchsia.media2/RealTime

何时应用此更新。

必填。

GainControl_SetGain_Response

在 fuchsia.audio/gain.fidl 中定义

Ordinal字段类型说明

GainControl_SetMute_Response

在 fuchsia.audio/gain.fidl 中定义

Ordinal字段类型说明

包

在 fuchsia.audio/stream_sink.fidl 中定义

描述通过 StreamSink 传送的数据包。

Ordinal字段类型说明
payload fuchsia.media2/PayloadRange

此数据包的载荷的位置。必须填写此字段。
timestamp Timestamp

指示应提供此数据包的时间戳。省略此字段意味着 unspecified_best_effort 时间戳。
capture_timestamp zx/Time

捕获此数据包的时间，以系统单调时间值表示。此字段是可选字段 可以由捕获器设置，以指示捕获此数据包的时间。
flags PacketFlags

描述数据包的标志。省略此字段意味着所有标志都清除。
front_frames_to_drop uint32

指示应该从 解码器。只能为压缩的流提供此值。 如果省略此字段，则不应丢弃任何前帧。
back_frames_to_drop uint32

指示应该从 解码器。只能为压缩的流提供此值。 如果省略此字段，则不应丢弃任何返回帧。
encryption_properties fuchsia.drm/PacketEncryptionProperties

说明应用于此数据包的加密。省略此字段意味着该数据包 未加密。

RampFunctionLinearSlope

在 fuchsia.audio/gain.fidl 中定义

增益在线性域上呈现线性斜率。

例如，从 -2.3dB 到 -1.6dB 的斜坡就是线性 从 0.1 到 0.5。如果延迟时长超过 4 毫秒， 获得更新：

  • 在 0 毫秒时，增益 = 0.1 = -2.3dB
  • 在 1 毫秒时，增益 = 0.2 = -2.0dB
  • 在 2 毫秒时，增益 = 0.3 = -1.8dB
  • 在 3 毫秒时，增益 = 0.4 = -1.7dB
  • 4 毫秒时，增益 = 0.5 = -1.6dB

请注意，dB 的变化遵循对数（非线性）曲线。

Ordinal字段类型说明

RampedGain

在 fuchsia.audio/gain.fidl 中定义

描述增量增益命令。应用此命令时，增益 超过指定的 持续时间。

Ordinal字段类型说明
target_gain_db float32
duration zx/Duration
function RampFunction

RingBuffer 资源

在 fuchsia.audio/ring_buffer.fidl 中定义

音频数据的环形缓冲区。

每个环形缓冲区都有一个生产方（写入该缓冲区）和一个使用方 （即从缓冲区读取数据的人员）。此外，每个环形缓冲区还会与 具有用于为缓冲区时间的参考时钟。

PCM 数据

PCM 音频的环形缓冲区是一个可能无限序列的窗口 帧数。每个帧都分配有一个“帧号”其中第一帧是 无限序列的编号为 0。帧 X 可以在环形缓冲区中找到 偏移 (X % RingBufferFrames) * BytesPerFrame，其中 RingBufferFrames 为 环形缓冲区的大小（以帧为单位），BytesPerFrame 是 单个帧。

并发协议

每个环形缓冲区都有一个生产方和一个消费方， 按时间同步。根据环形缓冲区的 参考时钟，我们定义了两个函数：

  • SafeWritePos(T) 是生成方最小（最早）的帧号 允许写入。生产方可以向此帧或任意 编号较大的帧。

  • SafeReadPos(T) 是使用方拥有的最高（最年轻）帧号 被允许读取。使用方可以读取此帧或任何较低编号的帧 帧。

为避免冲突，我们将这些属性定义为按 1 偏移：

SafeWritePos(T) = SafeReadPos(T) + 1

为避免竞选，必须有一个生产方，但可能有多个生产方 。此外，由于生产方和使用方是同步的， 随着时间的到来，我们需要显式围栏以确保缓存一致性： 生产者必须在每次写入后插入适当的栅栏（以刷新 CPU） 缓存并防止编译器对存储进行重新排序），且使用方必须 在每次读取之前插入一个适当的围栏（使 CPU 缓存失效并 防止编译器对加载进行重新排序）。

由于缓冲区大小有限，因此生产方/使用方无法执行写入/读取操作 无限未来/过去。我们为提供方分配P帧 C 帧发送给使用方，其中 P + C <= RingBufferFrames 和 P 以及 C 均由创建环形缓冲区的人员选择。

决定 P 和 C

在实践中，生产者/使用者通常会写入/读取批量帧 。例如，提供方可能每 Dp 唤醒一次 写入 DpFrameRate 帧的毫秒数，其中 FrameRate 是 PCM 视频流的帧速率如果提供方在时间 T 醒来，该提供方将最多花费 写入这些帧后的 Dp 个时间段。这意味着，它所需的最小帧数 SafeWritePos(T+Dp)，相当于 SafeWritePos(T) + DpFrameRate。提供方写入 DpFrameRate 帧 从这个位置开始整个地区（SafeWritePos(T)） 直到 2DpFrameRate 才会在时间 T 分配给提供方。制作 一个类似的参数，我们得出了以下限制：

P >= 2DpFrameRate
C >= 2Dc*FrameRate
RingBufferFrames >= P + C

因此，实际上，P 和 C 可以根据 生产者和使用方，其中最大批量大小受 环形缓冲区空间。

定义 SafeWritePos

SafeWritePos（以及隐式 SafeReadPos）的定义必须为 带外提供。

非 PCM 数据

非 PCM 数据的处理方式与 PCM 数据类似，不同之处在于位置 以“字节偏移量”表示而不是“帧号”，也就是 序列从字节偏移量 0 开始。

Ordinal字段类型说明
buffer fuchsia.mem/Buffer

实际环形缓冲区。producer_bytes 和 consumer_bytes 的总和 必须 <= buffer.size。

必填。
format Format

缓冲区中音频数据的编码。 必填。
producer_bytes uint64

分配给生产方的字节数。

对于 PCM 编码，P = producer_bytes / BytesPerFrame(format)，其中 P 必须是不可或缺的。

对于非 PCM 编码，没有任何限制，但单独的编码 可能会有更严格的要求。

必填。
consumer_bytes uint64

分配给使用方的字节数。

对于 PCM 编码，C = consumer_bytes / BytesPerFrame(format)，其中 C 必须是不可或缺的。

对于非 PCM 编码，没有任何限制，但单独的编码 可能会有更严格的要求。

必填。
reference_clock handle<clock>

环形缓冲区的参考时钟。

必填。
reference_clock_domain uint32

reference_clock 的域名。请参阅 fuchsia.hardware.audio.ClockDomain。 TODO(https://fxbug.dev/42066209)：如果 fuchsia.hardware.audio 不需要导入 fuchsia.audio 中，我们可以直接在下面使用该类型。

可选。如果未指定，则默认为 CLOCK_DOMAIN_EXTERNAL。

StreamSinkOnWillCloseRequest

在 fuchsia.audio/stream_sink.fidl 中定义

Ordinal字段类型说明
reason fuchsia.media2/ConsumerClosedReason

连接关闭的原因。

StreamSinkPutPacketRequest 资源

在 fuchsia.audio/stream_sink.fidl 中定义

Ordinal字段类型说明
packet Packet

描述数据包。必须填写此字段。
release_fence handle<eventpair>

在使用方完成数据包和缓冲区区域后关闭的事件对 可以重复使用数据包可按任意顺序释放。通过 释放栅栏可能会被该服务复制，因此必须在发送 ZX_RIGHT_DUPLICATE。此字段是可选字段。

StreamSinkStartSegmentRequest

在 fuchsia.audio/stream_sink.fidl 中定义

Ordinal字段类型说明
segment_id int64

标识细分。指定连接的新细分 ID 必须始终严格 不断增加。必须填写此字段。

StreamSinkWillCloseRequest

在 fuchsia.audio/stream_sink.fidl 中定义

Ordinal字段类型说明
reason fuchsia.media2/ProducerClosedReason

连接关闭的原因。

联合体

ChannelLayout 柔性环境

在 fuchsia.audio/format.fidl 中定义

表示音频基本流中声道的预期分配。

Ordinal变体类型说明
config ChannelConfig

此值用于说明每个渠道的分配情况。频道 配置必须符合 channel_count。

GainControl_SetGain_Result 严格

在 fuchsia.audio/gain.fidl 中定义

Ordinal变体类型说明
response GainControl_SetGain_Response
err GainError

GainControl_SetMute_Result strict

在 fuchsia.audio/gain.fidl 中定义

Ordinal变体类型说明
response GainControl_SetMute_Response
err GainError

GainUpdateMethod flexible

在 fuchsia.audio/gain.fidl 中定义

支持的增益更新类型。

Ordinal变体类型说明
gain_db float32

立即将增益设置为此值。
ramped RampedGain

使用斜坡逐步改变增益。

RampFunction 柔性

在 fuchsia.audio/gain.fidl 中定义

支持的梯度函数类型。

Ordinal变体类型说明
linear_slope RampFunctionLinearSlope

时间戳柔性环境

在 fuchsia.audio/stream_sink.fidl 中定义

指示音频数据包在流时间轴中的位置。

Ordinal变体类型说明
specified int64

直播时间轴中的特定时间。单位会有所不同，并且会在连接时提供 。
unspecified_continuous UnspecifiedContinuous

表示数据包应紧跟在上一个数据包之后显示（如果有） 先前的数据包如果没有上一个数据包，则此选项等同于 specified 值为 0。

此选项表示，即使数据包 晚点抵达。该数据包应紧跟在上一个数据包之后显示。 并且所得时间将保持不变，而不考虑数据包的到达时间。
unspecified_best_effort UnspecifiedBestEffort

表示数据包应在上一个数据包之后尽快呈现（如果 如果有，会尽快解决

此选项表示，如果数据包到达时间过晚，流式传输时间应“滑倒” 并且紧跟在上一个数据包之后呈现如果间隔 发生在无时间戳的流中，可能是由于上游源有损的。

位

PacketFlags 柔性环境

类型：uint32

在 fuchsia.audio/stream_sink.fidl 中定义

描述数据包的标志。

名称值说明
1

表示仅提供此数据包，以便之后的数据包可供解释。答 解码器应丢弃由该数据包生成的解压缩包。

常量

名称值类型说明
MAX_COMPRESSION_PARAMETERS_SIZE 32768 uint64

Compression.parameters 的大小上限。