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

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。