当前位置：首页 > news >正文

Media3 中 Window 的时间相关属性详解

news 来源：原创 2025/8/14 6:24:26

AndroidX Media3 的 Timeline.Window 类中，与时间相关的属性描述了媒体播放窗口（window）在时间维度上的关键信息。这些属性帮助开发者理解媒体的播放范围、起始点、持续时间以及与设备时间或直播流的同步关系。

Timeline.Window 的时间相关属性如下：

属性名	类型	描述
`presentationStartTimeMs`	`long`	媒体可播放的最早时间（毫秒，相对于 Unix 纪元），通常用于直播，可能为 `C.TIME_UNSET`。
`windowStartTimeMs`	`long`	窗口的实际开始时间（毫秒，相对于 Unix 纪元），通常用于直播，可能为 `C.TIME_UNSET`。
`elapsedRealtimeEpochOffsetMs`	`long`	窗口开始时间与设备 `elapsedRealtime()` 的偏移量（毫秒），用于时间同步，可能为 `C.TIME_UNSET`。
`defaultPositionMs`	`long`	默认播放起始位置（毫秒），相对于窗口开始，通常为 0 或上次播放位置。
`durationMs`	`long`	窗口总持续时间（毫秒），可能是 `C.TIME_UNSET`（如直播流）。
`positionInFirstPeriodMs`	`long`	窗口起始位置相对于第一个周期（period）的偏移量（毫秒）。

C.TIME_UNSET（值为 -9223372036854775807L）表示时间未设置，常用于直播或未完全加载的媒体。属性分为绝对时间（相对于 Unix 纪元，如 presentationStartTimeMs）和相对时间（相对于窗口内部，如 defaultPositionMs）。

`presentationStartTimeMs`

类型：long（毫秒）
含义：
- 表示媒体内容可播放的最早时间，基于 Unix 纪元（1970-01-01 00:00:00 UTC）。
- 通常用于直播流，定义直播内容的理论开始时间。
- 如果未设置（C.TIME_UNSET），表示时间未知（常见于点播或未加载完成的直播）。
用途：
- 帮助播放器确定直播流的有效时间范围。
- 用于计算直播流的延迟（currentPosition - presentationStartTimeMs）。
在窗口时间轴上的位置：
- 通常是时间轴的最左侧点，表示窗口可播放的最早时间。
- 如果为 C.TIME_UNSET，在时间轴上可能是未定义的起点（用虚线或注释表示）。
示例：
- 假设直播流在 2023-10-01 10:00:00 UTC 开始，presentationStartTimeMs 可能为 1696154400000（毫秒）。

`windowStartTimeMs`

类型：long（毫秒）
含义：
- 表示窗口的实际开始时间，基于 Unix 纪元，可以落后presentationStartTimeMs一天或者更久，是window实际开播时间。
- 通常用于直播流，表示播放器可以访问的直播内容的开始时间（可能比 presentationStartTimeMs 稍晚）。
- 如果未设置（C.TIME_UNSET），表示时间未知（常见于点播或直播缓冲区未初始化）。
用途：
- 确定直播窗口的实际可播放范围。
- 与 elapsedRealtimeEpochOffsetMs 结合，用于同步设备时间和直播时间。
在窗口时间轴上的位置：
- 位于 presentationStartTimeMs 之后（或重叠），是时间轴的实际起点。
- 在直播场景中，它通常是播放器开始加载内容的时刻。
- 如果为 C.TIME_UNSET，在时间轴上可能是未定义的起点。
示例：
- 直播流可能在 presentationStartTimeMs 后几秒开始缓冲，windowStartTimeMs 为 1696154405000（比 presentationStartTimeMs 晚 5 秒）。

`elapsedRealtimeEpochOffsetMs`

类型：long（毫秒）
含义：
- 表示 windowStartTimeMs（Unix 纪元时间）与设备 elapsedRealtime()（设备启动后的毫秒数）之间的偏移量。
- 公式：windowStartTimeMs = elapsedRealtime() + elapsedRealtimeEpochOffsetMs。
- 用于同步直播流的绝对时间与设备本地时间。
- 如果未设置（C.TIME_UNSET），表示无法同步（常见于点播或直播未提供时间信息）。
用途：
- 在直播场景中，帮助播放器将本地时间转换为直播流的绝对时间。
- 用于精确计算直播流的当前播放位置（currentPositionMs + elapsedRealtimeEpochOffsetMs）。
在窗口时间轴上的位置：
- 不在时间轴上的直接点，而是作为 windowStartTimeMs 的参考偏移。
- 在图中通常标注为时间轴外的箭头或注释，指向 windowStartTimeMs，表示偏移关系。
示例：
- 如果 windowStartTimeMs = 1696154405000，当前 elapsedRealtime() = 1000000，则 elapsedRealtimeEpochOffsetMs = 1696154405000 - 1000000。

`defaultPositionMs`

类型：long（毫秒）
含义：
- 表示播放器默认开始播放的位置，相对于窗口的逻辑起点（通常是 windowStartTimeMs 或窗口的 0 点）。
- 对于点播，通常为 0（从头播放）或上次播放位置（续播）。
- 对于直播，通常接近窗口的末端（最新可用内容）。
用途：
- 确定播放器初始化时的播放位置。
- 用户可以通过 seekTo(defaultPositionMs) 跳转到该位置。
在窗口时间轴上的位置：
- 位于时间轴的起始段，通常接近窗口的逻辑起点（0ms 或 windowStartTimeMs）。
- 在点播中，它可能是时间轴的 0 点；在直播中，它可能靠近 durationMs 的末端。
示例：
- 点播视频：defaultPositionMs = 0（从头开始）。
- 直播流：defaultPositionMs = 30000（距离窗口末端 30 秒）。

`durationMs`

类型：long（毫秒）
含义：
- 表示窗口的总持续时间（毫秒），从逻辑起点到结束。
- 对于点播，是视频的总长度（如 3600000ms 表示 1 小时）。
- 对于直播，可能是缓冲区长度，或 C.TIME_UNSET（表示未知，如无限直播）。
用途：
- 确定播放器可播放的时间范围。
- 用于进度条显示和 seek 操作（seekTo(positionMs < durationMs)）。
在窗口时间轴上的位置：
- 表示时间轴的整个长度，从逻辑起点（通常 defaultPositionMs 或 0）到结束点。
- 如果为 C.TIME_UNSET，时间轴末端可能是开放的（用箭头或虚线表示）。
示例：
- 点播：durationMs = 600000（10 分钟视频）。
- 直播：durationMs = C.TIME_UNSET（无限直播）或 60000（60 秒缓冲区）。

`positionInFirstPeriodMs`

类型：long（毫秒）
含义：
- 表示窗口的逻辑起点相对于第一个周期（Timeline.Period）的偏移量。
- Timeline 由多个周期组成，每个周期可能代表媒体的一个片段（如 HLS 的分片）。
- 该属性定义窗口的起始点在第一个周期内的具体位置。
用途：
- 用于多周期媒体（如 DASH、HLS）中，确定窗口与周期的相对位置。
- 帮助播放器在周期边界正确 seek 或切换。
在窗口时间轴上的位置：
- 位于 defaultPositionMs 附近，通常是子偏移，表示窗口起点在第一个周期内的位置。
- 如果窗口只有一个周期，positionInFirstPeriodMs 可能等于 defaultPositionMs。
示例：
- HLS 流，第一个周期为 10 秒，窗口从第 5 秒开始：positionInFirstPeriodMs = 5000。

presentationStartTimeMs

windowStartTimeMs

elapsedRealtimeEpochOffsetMs

defaultPositionMs

durationMs

positionInFirstPeriodMs