> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.sleepcycle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Android 版本说明

## 版本 1.2.0

### 新功能

* **睡眠评分**：使用 `SleepScoring.compute(result, history, dateOfBirthSecondsUtc, chronoType)` 计算单晚的睡眠评分，它返回一个 `SleepScore`，包含 `total`、`duration`、`quality` 和 `routine` 子评分（每项均为 0.0–1.0）。通过 `AnalysisResult.toSleepScoreHistoryEntry()` 从已完成的结果构建历史记录条目，并通过 `SleepScoring.identifyChronoType(history)` 推导用户的 `ChronoType`。
* **扩展音频事件**：新增 `extendedAudioEvents` 功能标志，公开标准集之外的额外 `EventType` 值。
* **结果中的实时睡眠分期**：`AnalysisResult` 现在包含 `realTimeSleepStageIntervals`，即会话期间实时发出的睡眠分期（与会话结束后的 `sleepStageIntervals` 并存）。

### API 变更

* `AudioEventListener.onAudioAnalysisBatchCompleted()` 现在接收 `audioProbability: Map<EventType, Float>`，即每批次中每种事件类型的概率。`rms: FloatArray` 参数已替换为 `dbSpl: FloatArray`，提供以 dB SPL 表示的 A 计权声音音量。
* `EventEndedInfo` 现在包含 `eventType: EventType` 属性。
* `AnalysisResult` 现在包含 `timeZoneId: String`（会话开始时捕获的 IANA 时区）和 `realTimeSleepStageIntervals: List<SleepStageInterval>`。

## 版本 1.1.1

### 新功能

* **智能闹钟**：通过 `SmartAlarmConfig` 配置唤醒时段，并通过新增的 `smartAlarmFlow: SharedFlow<SmartAlarmEvent>` 观察闹钟生命周期事件（`Armed`、`Triggered`）。触发原因包括 `OPTIMAL_WAKE_UP`、`USER_INTERACTION` 和 `WINDOW_END`。智能闹钟受 `SleepAnalysisFeatures.smartAlarm` 限制，仅在主声道上支持。
* **立体声声道分离**：新增 `ChannelSeparationConfig`，控制立体声音频声道如何分配到分析声道，内置预设为 `BED_SIDE_MICS`、`CENTERED_MIC_ARRAY` 和 `DETECTION_STRENGTH_ONLY`。

### API 变更

* 在 `startAnalysis()` 和 `startMultiChannelAnalysis()` 中新增 `smartAlarmConfig: SmartAlarmConfig?` 参数。
* 在 `startAnalysis()`、`startDataSource()` 和 `resumeAnalysis()` 中新增 `channelSeparationConfig: ChannelSeparationConfig` 参数。
* 在 `initialize()` 中新增 `forceTokenRefresh: Boolean` 参数，即使存在缓存令牌也可强制重新获取。
* `resumeAnalysis()` 现在返回 `List<ResumedSession>`（不再是 `Boolean`），为每个恢复的会话提供会话 ID、声道和智能闹钟配置。
* 当启用加速度计时，`createLiveDataSource()` 现在会同时启用陀螺仪。
* 当 SDK 未初始化时，`stopDataSource()` 和 `stopAnalysis()` 不再抛出异常，而是平稳返回。

## 版本 1.1.0

### 新功能

* **多声道分析**：使用立体声音频同时分析两个声道。新增 `startDataSource()` / `stopDataSource()` 方法，将数据源生命周期与会话生命周期分离；通过 `startMultiChannelAnalysis(channel:)` 在各声道上分别启动会话，通过 `stopAnalysis(sessionId:)` 单独停止某个会话。
* **音频运行状况监测**：新增 `audioHealthFlow: SharedFlow<AudioHealthUpdate>`，实时发出音频输入运行状况的变化（`HEALTHY`、`FLATLINE`、`MISSING_INPUT`）。分析结果中包含 `AudioStatistics` 和 `AudioHealthInterval`。
* **所有公共类型上的会话 ID**：`Event`、`BreathingRate`、`SleepStageInterval`、`AudioClip` 和 `AudioHealthUpdate` 现在都包含 `sessionId: UUID` 属性，用于标识它们所属的会话。

### API 变更

* `startAnalysis()` 现在返回一个标识会话的 `UUID`。
* 在 `startAnalysis()` 中新增 `tag: String?` 参数，用于为会话打标签。
* `AudioEventListener.onAudioAnalysisBatchCompleted()` 现在包含 `sessionId: UUID` 参数。
* `AnalysisResult` 现在包含 `sleepStageIntervals`、`audioStatistics` 和 `sessionId` 属性。
* 在 `SleepAnalysisFeatures` 中新增 `multiChannelAnalysis`。

## 版本 1.0.10

**发布日期：** 2026 年 1 月 26 日

### 新功能

* 磁盘空间检查：SDK 现在会在开始分析前检查是否有足够的磁盘空间，若空间不足则抛出 `SdkNotEnoughDiskSpaceException`。

### API 变更

* 新增 `SdkNotInitializedException` 异常，当在初始化之前调用 SDK 方法时抛出。
* 在 `startAnalysis()` 上为 `SdkNotInitializedException` 和 `SdkNotEnoughDiskSpaceException` 增加了 `@throws` 文档说明。

### 错误修复

* 改进了写入数据库时的错误处理，避免在磁盘空间不足时崩溃。

## 版本 1.0.9

**发布日期：** 2026 年 1 月 15 日

### 新功能

* 首选音频设备：可通过 `createLiveDataSource()` 中的 `preferredDevice` 参数指定首选音频输入设备。

### API 变更

* 新增对立体声音频输入的支持。
* `startAnalysis()` 和 `resumeAnalysis()` 中的 `dataSource` 参数现在是必填的（非空），默认值为 `createLiveDataSource()`。
* 新增 `createLiveDataSource()` 工厂方法，用于创建从设备传感器采集数据的实时数据源。
* 将 `LiveDataSource` 类公开，允许直接实例化以进行自定义配置。
* 扩展了 `DataSource` 接口，新增以下方法：
  * `audioOutputEnabled()` - 检查是否启用了音频输出
  * `accelerometerOutputEnabled()` - 检查是否启用了加速度计输出
  * `getAudioFormat()` - 返回音频声道配置（MONO 或 STEREO）
* 发布的工件现在包含源文件（不含内部包），便于调试。