Android 版本说明

版本 1.3.2

问题修复与改进。

版本 1.3.0

新功能

• 精简版 SDK：SDK 现在以两个构件发布，二者由同一份源码构建，并暴露完全相同的 com.sleepcycle.sdk API。com.sleepcycle.sdk:sdk-android 与以往一样将加密的机器学习模型内嵌在 AAR 中；新增的 com.sleepcycle.sdk:sdk-android-slim 不携带模型，而是在首次调用 initialize() 时下载您已获授权的功能所需的模型，使构件减少约 15 MB。请只依赖其中之一；切换无需修改任何代码。详见 Android 指南的「安装」一节。
• 下载进度：initialize() 新增 onDownloadProgress: ((Float) -> Unit)? 回调，以 0.0..1.0 之间的比例报告模型下载进度。当无需下载时会立即以 1.0 调用，因此同一份代码对两个构件均适用。
• 会话进行中修改智能闹钟：updateSmartAlarm(config: SmartAlarmConfig?) 可替换活动会话启动时设置的闹钟、为未设置闹钟的会话添加闹钟，或在传入 null 时取消闹钟。该配置会被持久化，因此进程被杀后恢复的会话会沿用它；已经触发过的闹钟会被新配置重新装载，从而可以再次触发。
• 清除持久化状态：clear(context) 会销毁 SDK 并清除缓存的授权令牌、存储的内容密钥以及所有已下载的模型。下一次 initialize() 将重新授权并重新下载所需内容。
• 丢弃可恢复的会话：clearActiveSessions() 结束 resumeAnalysis() 将会接管的会话并丢弃其结果，使 isResumePossible() 重新返回 false。

API 变更

• initialize() 新增 onDownloadProgress: ((Float) -> Unit)? 参数。当已获授权的功能所需的模型无法就绪时，它现在还会抛出新增的 SdkResourceException；当剩余磁盘空间不足以下载模型时，抛出 SdkNotEnoughDiskSpaceException。
• Logger 接口中移除了 Logger.setLogLevel(level)。日志级别过滤现在由 SDK 负责，因此自定义 Logger 只需实现 d()、i()、w() 和 e()。仍可通过 initialize() 的 logLevel 参数和 SleepCycleSdk.setLogLevel() 设置级别。
• 当为 AnalysisChannel.PRIMARY 以外的声道传入 smartAlarmConfig 时，startMultiChannelAnalysis() 现在会抛出 SdkFeatureUnavailable，而不再静默忽略。
• destroy() 不再结束活动会话。它会停止数据源并保留会话的可恢复性，因此被应用关闭中断的会话可以再次通过 resumeAnalysis() 接管。若要结束这些会话，请先调用 stopAnalysis() 或 stopDataSource()，或事后调用 clearActiveSessions()。

改进

• 更低的内存与 CPU 占用：推理会话在整夜分析期间的内存占用与 CPU 时间显著降低。
• 多项问题修复与改进。

版本 1.2.1

改进

• 更小的 SDK 体积：SDK 现在捆绑的是精简版 ONNX Runtime，而非完整运行时，每个架构的原生库体积减少约 24 MB。
• 改进的音频分类：更新了音频分类模型，提升了声音检测效果。

版本 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）
• 发布的工件现在包含源文件（不含内部包），便于调试。