Skip to content

播报

功能介绍

语音播报（Audio Guidance）在导航或巡航过程中，向 HMI 提供可朗读的引导文案或提示音。播报内容来源包括：

来源 AudioInstruction.audioType 说明
转向引导 INFO / FIRST / SECOND / THIRD / REPEAT 导航会话中的分阶段 TBT 播报与重复播报
Alert ALERT 电子眼、限速等 Alert 关联语音（依赖 Alert 模块）
业务主动请求 REQUEST 通过 AudioGuidanceManager.requestAudioData / requestAudio 触发的系统提示

HMI 职责： SDK 只生成播报数据（纯文本 audioOrthographyString、音素串 audioPhonemeString 或纯提示音），不负责播放。集成方在 AudioInstructionEventListener 中接入 TTS 或自定义音频，并处理与收音机、媒体、通话等通道的冲突。

前置条件： 已完成 NavigationService 初始化。默认开启语音播报；关闭 Alert 时会连带关闭播报（见下文开关说明）。

阶段解释

转向引导会按距离与场景分阶段播报，通过 AudioInstruction.audioType 区分阶段。各阶段（INFO～THIRD）在每个转弯点通常只自动播报一次；实际触发距离会随路型、车速等动态调整，下表距离仅供参考。

阶段 说明
INFO 远距离提示，一般在距转弯点 2 km 以上。多用于长路段上确认继续沿当前道路行驶。
FIRST 第一声提示，约 800 m。简要告知稍后需转弯、驶出等，通常不含详细路名。
SECOND 第二声提示，约 300 m。信息最完整，说明如何转向、目标道路或方向。
THIRD 临近转弯点。短句直接指导操作，如「右转」「靠左行驶」。
REPEAT 重复播报。由 HMI 调用 NavigationSession.requestLastAudioInstruction() 触发；回调中 audioType 为 REPEAT。

流程概览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
NavigationService.Factory.createInstance(options)     ← 默认开启 AudioGuidance
        ↓
eventHub.addAudioInstructionEventListener(listener)
navigationService.audioGuidanceManager.*            ← verbosity / 白名单 / 主动请求
navigationService.settings.updateAudioLocale(...)   ← 可选：播报语言与界面语言分离
        ↓
导航中 / 巡航中 / 业务 requestAudio*
        ↓
onAudioInstructionUpdated(AudioInstruction)         ← Message 线程（与 eventHub 其他回调同线程）
        ↓
HMI：TTS 播放 TEXT，或播放 TONE

核心接口

接口 / 类 作用
NavigationServiceOptions 创建服务时 disableAudioGuidance() 关闭播报；disableAlert() 会同时关闭 Alert 与其播报
NavigationService.audioGuidanceManager AudioGuidanceManager：verbosity、播报类型白名单、主动请求播报
NavigationSession 导航会话；requestLastAudioInstruction() 触发 REPEAT 转向重复播报
NavigationService.settings Settings.updateAudioLocale：设置播报所用语言；若与系统语言不一致，以此处设置为准
NavigationService.eventHub 注册 AudioInstructionEventListener，接收 SDK 下发的每一条播报
AudioInstructionEventListener onAudioInstructionUpdated：有一条新播报时回调，传入本次要读的文案或提示音信息
AudioInstruction 一条播报的具体内容：类型、文本/音素、是念出来还是只响提示音
AudioGuidanceManager 见下表
AudioPromptType 预设播报模板类型（Alert 类、系统提示类等）
AudioRequest 带距离、路名、ETA 等占位参数的播报请求
VerbosityLevel 转向引导详细程度（不影响 Alert / REQUEST）
PromptStyle TEXT（文本）或 TONE（纯提示音）

AudioGuidanceManager

API 说明
requestAudioData(audioPromptType) 按预设类型请求一条播报（如 START_NAVIGATION、DEVIATION）
requestAudio(request) 使用 AudioRequest 传入类型及模板占位字段（距离、路名、Route 等）
setVerbosityLevel(level) 设置 TBT 播报详细度，默认 VERBOSE
setEnabledAudioPrompts(types) 白名单：仅启用集合内的 AudioPromptType；多次调用以最后一次为准
disableAudioPrompt(types) 已废弃，请用 setEnabledAudioPrompts

Settings.updateAudioLocale（播报语言）

API 说明
navigationService.settings.updateAudioLocale(locale) 设置播报所用语言

当接口调用成功后，播报语言将切换为指定语言，并且后续即使系统语言发生变化，播报语言也不会自动更新。

地图与界面文案语言仍由主 SDK 的 SDKOptions.setLocale，SDK.updateLocale 等接口控制。典型使用场景：界面使用一种语言，而语音播报使用另一种语言（例如界面为英语、播报为德语）。

如果没有特殊需求，则无需调用该 API，播报语言会默认跟随系统语言。

1
2
// 仅覆盖播报语言：
navigationService.settings.updateAudioLocale(com.telenav.sdk.core.Locale.GERMAN)

关键参数

API 说明 默认
（不调用） 开启 Audio Guidance 开启
disableAudioGuidance() 关闭播报组件；无 onAudioInstructionUpdated —
disableAlert() 关闭 Alert；同时关闭其播报（依赖关系） —

AudioInstruction

字段 说明
audioType INFO / FIRST / SECOND / THIRD / REPEAT（导航 TBT）、ALERT、REQUEST
promptStyle TEXT：使用文本（正字法/音素）；TONE：仅提示音，通常无正文
promptType 对应 AudioPromptType；对 Alert / REQUEST 有效
audioOrthographyString 推荐给 Android TTS 的正字法字符串
audioPhonemeString 带 <phoneme> / <language> 标记的音素串 (HERE标准的 NT-SAMPA格式)，适合支持此格式音素的引擎

PromptStyle 处理建议

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
override fun onAudioInstructionUpdated(audioInstruction: AudioInstruction) {
    when (audioInstruction.promptStyle) {
        PromptStyle.TEXT -> {
            val text = audioInstruction.audioOrthographyString
            if (!text.isNullOrEmpty()) {
                // 使用 TTS 播放 text，或按引擎能力解析 audioPhonemeString
            }
        }
        PromptStyle.TONE -> {
            // 播放短提示音，无路线语义文本
        }
    }
}

VerbosityLevel（仅影响转向引导）

取值 说明
VERBOSE 默认；各阶段 TBT 均播报
MEDIUM 部分阶段不播报（如默认不播 FIRST）
MINIMUM 只提供 THIRD，部分复杂情况提供 SECOND
TONEONLY 只提供 SECOND、THIRD，并且 style 为 TONE
MUTE 不输出 TBT 播报 
1
navigationService.audioGuidanceManager.setVerbosityLevel(VerbosityLevel.MINIMUM)

AudioPromptType

AudioPromptType 用于 requestAudioData / requestAudio 指定播报模板，也可用于 setEnabledAudioPrompts 白名单。大体分为 Alert 关联播报 与 系统/业务提示 两类。除 TRIP_SUMMARY 外，一般使用 requestAudioData(type) 即可；TRIP_SUMMARY 需通过 AudioRequest 传入行程相关字段。

常量 值 说明 额外参数（AudioRequest）
SPEED_CAMERA 0 前方有测速摄像头 —
RED_LIGHT_CAMERA 1 前方有红绿灯违章摄像头 —
BUS_LANE_CAMERA 2 前方有公交车道摄像头 —
RED_LIGHT_AND_SPEED_CAMERA 3 前方有红灯测速摄像头 —
SECTION_START_CAMERA 4 前方有测速区间 —
SECTION_END_CAMERA 5 前方离开测速区间 —
TRAFFIC_RULE_CAMERA 19 交通规则摄像头 —
TOLLBOOTH 20 前方收费 —
SCHOOL_ZONE 100 前方有学校路段 —
CROSSING_RAILWAY 120 前方有铁路道口 —
ACCIDENT_AHEAD 136 前方发生事故 —
ACCIDENT_CLEARED 137 事故已清除 —
ENTRY_BLOCKED 138 入口封锁 —
ENTRY_REOPENED 139 入口重新开启 —
EXIT_BLOCKED 140 出口封锁 —
EXIT_REOPENED 141 出口重新开启 —
HAZARDOUS_ROAD_AHEAD 142 前方路段有危险 —
HAZARDOUS_ROAD_PASSED 143 已经通过危险路段 —
LANE_RESTRICTIONS_AHEAD 144 前方有车道限制 —
LANE_RESTRICTIONS_OVER 145 车道限制路段结束 —
POLICE_CHECK_POINT_AHEAD 146 前方路段有警方检查点 —
ROAD_BLOCK_AHEAD 147 前方路段道路封闭 —
ROADWORKS_AHEAD 148 前方有道路施工 —
ROADWORKS_ENDED 149 道路施工路段结束 —
CONGESTION_AHEAD 150 前方拥堵 —
CONGESTION_CLEARED 151 道路施工路段结束 —
MOBILE_SPEED_CAMERA 153 前方有移动测速区间 —
TIME_SPEED_LIMIT 154 前方有限速区域 —
OVER_SPEED 162 您已超速 —
CONGESTION_HAZARD 216 前方有拥堵路段 —
ACCIDENT_HAZARD 217 前方有事故高发区 —
TRAFFIC_MERGE_AHEAD 218 前方车辆汇入 / 前方左侧车辆汇入 / 前方右侧车辆汇入（对应 AlertType::HIGHWAY_MERGE_POINT） —
ROUTE_SUMMARY 223 路线摘要（已废弃，请用 TRIP_SUMMARY） —
TRIP_SUMMARY 225 行程摘要（到达时间等） distance、ete、dateTime（必填）；is24h、isTimezoneChanged；可用 AudioRequest.Builder.setRoute(route) 进行设置
APPROACHING_INTERSECTION 232 路口减速提示 —
MULTIPLE_RESTRICTIONS_BLOCKED 233 警告前方有限制，无法通行（不可单独开关） —
WEIGHT_RESTRICTION_BLOCKED 234 警告前方限重，无法通行 —
LENGTH_RESTRICTION_BLOCKED 235 警告前方有长度限制。无法通行 —
HEIGHT_RESTRICTION_BLOCKED 236 警告前方限高无法通行 —
WIDTH_RESTRICTION_BLOCKED 237 警告前方限宽，无法通行 —
TIMED_RESTRICTION_BLOCKED 238 警告前方时段限行，无法通行 —
TUNNEL_RESTRICTION_BLOCKED 239 警告前方隧道限行，无法通行 —
HAZARDOUS_MATERIAL_PROHIBITED 240 前方道路禁止危险物品运输车辆通行 —
TRUCK_PROHIBITED 241 警告前方禁止卡车通行，无法通行 —
SHARP_TURN 242 前方急转弯，请谨慎驾驶 —
STEEP_HILL_DOWNWARD 243 前方下陡坡请减速慢行 —
ROAD_HUMP 244 前方有路丘，请减速慢行 —
TRUCK_TILT 245 前方路段有翻车风险，请减速慢行 —
ROAD_NARROWS 246 前方道路变窄 —
STEEP_HILL_UPWARD 247 前方陡坡上行 —
TRAILER_PROHIBITED 248 注意前方有拖车限制，无法通行。 —
AXLE_RESTRICTION_BLOCKED 249 注意前方存在车轴限制无法通过 —
START_NAVIGATION 401 现在开始导航 —
OFF_ROAD 402 请沿高亮路线行驶 —
DEVIATION 404 您已偏航 —
START_REROUTE_BY_TRAFFIC 407 因交通事件重新算路 —
REROUTING 408 正在重新规划路线 —
AUTO_EXIT_NAVIGATION 411 已完成路线规划 —
RESUME_ROUTE 412 继续导航 —
CALCULATING_ROUTE 413 正在计算路线 —
CALCULATE_ROUTE_FAILED 414 算路失败，请重新输入终点 —
DISCLAIMER_MESSAGE 416 请遵守交规 —
COUNTRY_BORDER_PREP 419 接近国境线 —
INCOMPLETE_MAP 421 您所在区域地图数据不完整请谨慎跟随 —
FOUR_WD_OFF_ROAD 425 沿轨迹回到高亮路线（四驱离路） —
BATTERY_INSUFFICIENT_THEN_ADD_CHARGER 500 当前电量无法到达目的地，已为您添加充电站 —
BATTERY_INSUFFICIENT_THEN_UPDATE_CHARGERS 501 当前电量无法到达目的地，已为您重新规划充电站 —
BATTERY_INSUFFICIENT_CANNOT_REACH_DESTINATION 502 当前电量无法到达目的地 —
INVALID 1000 无效类型 —

完整占位字段与模板句式以 SDK 源码 AudioPromptType.kt、AudioRequest.kt 中 KDoc 为准。

纯文本与音素

AudioInstruction 在 promptStyle == TEXT 时，可同时提供两种可读字符串，由 HMI 选用的 TTS 引擎决定使用哪一种：

字段 说明
audioOrthographyString 纯文本，直接交给 TTS 即可，接入简单
audioPhonemeString 音素串（含 <phoneme> / <language> 等标记）发音更准确；当播报模板语言与路名等现场词语言不一致时，听感通常更好

若引擎支持 NT-SAMPA 格式的音素，可优先使用 audioPhonemeString；否则使用 audioOrthographyString。

示例代码

1. 创建服务并注册监听

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
val navigationService = NavigationService.Factory.createInstance(
    NavigationServiceOptions.Builder()
        // .disableAudioGuidance()   // 不需要播报时关闭
        .build()
)

navigationService.eventHub.addAudioInstructionEventListener(
    object : AudioInstructionEventListener {
        override fun onAudioInstructionUpdated(audioInstruction: AudioInstruction) {
            // 回调在 Message 线程，播放前如需更新 UI 请切主线程
            playAudioInstruction(audioInstruction)
        }
    }
)

// 不再需要时
navigationService.eventHub.removeAudioInstructionEventListener(listener)

2. 播报语言与 TTS 示例

1
2
3
4
5
6
7
8
9
navigationService.settings.updateAudioLocale(com.telenav.sdk.core.Locale.GERMAN)

// 示例：系统 TextToSpeech 播放纯文本（集成方自选引擎）
tts.speak(
    audioInstruction.audioOrthographyString,
    TextToSpeech.QUEUE_FLUSH,
    null,
    ""
)

3. 主动请求系统提示

1
2
3
4
// 简单类型：仅指定 AudioPromptType
navigationService.audioGuidanceManager.requestAudioData(AudioPromptType.CALCULATING_ROUTE)

navigationService.audioGuidanceManager.requestAudioData(AudioPromptType.START_NAVIGATION)

算路失败、偏航、离路等场景可在业务逻辑中主动请求，例如：

1
2
3
4
5
// 算路失败
navigationService.audioGuidanceManager.requestAudioData(AudioPromptType.CALCULATE_ROUTE_FAILED)

// 导航偏航（NavigationEvent.deviated == true）
navigationService.audioGuidanceManager.requestAudioData(AudioPromptType.DEVIATION)

4. 带参数的播报请求（AudioRequest）

1
2
3
4
5
6
val request = AudioRequest.Builder(AudioPromptType.TRIP_SUMMARY)
    .setRoute(route)           // 填充 distance、ete、dateTime、isTimezoneChanged 等
    .is24h(true)
    .build()

navigationService.audioGuidanceManager.requestAudio(request)

5. 限制播报类型（白名单）

1
2
3
4
5
6
7
navigationService.audioGuidanceManager.setEnabledAudioPrompts(
    setOf(
        AudioPromptType.SPEED_CAMERA,
        AudioPromptType.START_NAVIGATION,
        AudioPromptType.DEVIATION
    )
)

6. 重复上一句转向引导（REPEAT）

1
2
3
// 须在导航进行中，且已注册 AudioInstructionEventListener
val ok = navigationSession?.requestLastAudioInstruction() ?: false
// 成功后 onAudioInstructionUpdated 收到 audioType == REPEAT 的 AudioInstruction

注意事项

  • 关闭 Alert 即无 Alert 播报： disableAlert() 会关闭 Alert 与 Audio Guidance；仅需关闭沿途检测但保留 TBT 时，不要调用 disableAlert()，应通过 alertManager 子开关控制。
  • 线程： onAudioInstructionUpdated 在 Message 线程 执行，与 eventHub 其他监听相同；耗时播放准备建议在 HMI 工作线程异步处理，避免阻塞 SDK 回调。
  • 监听注销： 退出导航页时调用 removeAudioInstructionEventListener(listener)
  • Verbosity 仅作用于 TBT： setVerbosityLevel 不改变 Alert 或 requestAudio* 触发的 REQUEST 播报逻辑。
  • 白名单模式： 一旦调用 setEnabledAudioPrompts，仅列表内类型会播报。