Skip to content

Audio Prompt For Turn By Turn Navigation

Audio prompt for turn-by-turn navigation

This tutorial shows how to handle audio prompts for turn-by-turn navigation.

Get started

If a drive session is created with both audio and navigation components enabled, after navigation starts along a route, the drive session will provide audio prompts for turn-by-turn navigation experience.

Audio prompts for turn-by-turn navigation is organized in four phases: * tn::drive::models::v1::AudioInstruction::AudioType::Info phase when vehicle is very far away from the maneuver point * tn::drive::models::v1::AudioInstruction::AudioType::First phase when vehicle is far away from the maneuver point * tn::drive::models::v1::AudioInstruction::AudioType::Second phase when vehicle is near the maneuver point that preparation should be made * tn::drive::models::v1::AudioInstruction::AudioType::Third phase when vehicle is at the maneuver point that action should be taken

Following table shows some samples of audio prompt content for different phases.

Phase Turn action Prompt content Comment
Info action does not affect prompt content proceed on Ygnacio Valley Rd (when step length is greater than 8.5km on highway) Info phase guidance will be prompted when entering an extremely long step. There are two types of info prompts, with and without distance. The one without distance is only given when the step is extremely long.
proceed 3 kilometers on Ygnacio Valley Rd (when the step length on the highway is 5km-8.5km)
First enter roundabout in 500 meters enter the roundabout and take the second exit In most cases, the first phase guidance won't contain road name information.
exit right in 1.5 kilometers use the two right lanes to exit right to I 405 south towards Long Beach
turn right in 500 meters turn right
u-turn in 500 meters make a u-turn if possible
arrival destination in 800 meters you will arrive at your destination
Second exit roundabout in 100 meters take the second exit to Crawford St Second phase guidance provides most of the information to prepare for the turn. In rare cases, first and second phase guidance will share exactly the same content.
turn right in 300 meters turn right to 34th St
u-turn in 200 meters make a u-turn if possible at Sullivan St
arrival destination in 300 meters your destination is on your left
Third exit roundabout take the first exit Third phase guidance is given when vehicle is approaching the maneuver point, so it should be short and accurate.
exit right exit right to I 405 south
turn right turn right to Huntington Dr
u-turn make a u-turn if possible at 5th Avenue
arrival destination you have reached your destination on your right

Handle audio prompt for turn-by-turn navigation

Make a customized audio listener to handle turn-by-turn navigation prompts. Refer to tutorial for audio instructions for how to play audio instructions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
class AudioInstructionObserver : public tn::drive::api::AudioEventListener
{
public:
    void onAudioInstruction(const tn::drive::models::v1::AudioInstruction& instruction) override
    {
        // audio instructions for each phase of each turn will be prompted only once by drive session
        if ((instruction.type == tn::drive::models::v1::AudioInstruction::AudioType::Info) ||
            (instruction.type == tn::drive::models::v1::AudioInstruction::AudioType::First) ||
            (instruction.type == tn::drive::models::v1::AudioInstruction::AudioType::Second) ||
            (instruction.type == tn::drive::models::v1::AudioInstruction::AudioType::Third))
        {
            // you should check if there's any audio guidance prompt being played before playing a new one
            // to avoid conflict with existing one
            playAudioInstruction(instruction);
        }
        // omit other types ...
    }
};

Request latest audio prompt for turn-by-turn navigation

Since audio instructions for each phase of each turn will be prompted only once by drive session, user may want to hear the prompt again for some cases. Navigation session provides a way to request the latest audio prompt for turn-by-turn navigation prompts. The latest audio prompt provided in this way is not simply the repeating of last audio prompt, but with latest navigation status updates, including vehicle speed, distance to turn, etc.. Refer to guide for navigation session for starting a navigation session.

1
2
// request latest audio prompt for turn-by-turn navigation
navigationSession->requestAudioGuidance();

Customize verbosity level for turn-by-turn navigation prompts

Verbosity level for turn-by-turn navigation prompts can be tuned to meet user's expectation. Drive session provides five levels of audio prompt verbosity. * Verbose: all turn-by-turn navigation prompt will be available which is the default level * Medium: the First phase audio prompts won't be provided in this level * Minimum: the Info and First phase audio prompts won't be provided in this level, the Second and Third phase audio prompts won't be provided for simple turns * ToneOnly: the Info and First phase audio prompts won't be provided in this level, the Second and Third phase audio prompts will be provided in tone style * Commute: no audio prompts will be provided

Notice: verbosity level only affects turn-by-turn navigation prompts, alert prompts are not affected.

1
2
// adjust verbosity level
driveSession->setVerbosityLevel(tn::drive::models::v1::VerbosityLevel::Medium);

Request additional audio prompt for navigation

Drive session provides additional audio prompts for navigation to cover various use cases. For example, at the beginning of a navigation session, you could request a StartNavigation audio prompt to indicate a navigation session has been launched.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// start a navigation session
tn::drive::api::NavigationSessionOptions navigationOptions;
navigationOptions.enable_audio = true;
auto* navigationSession = driveSession->startNavigation(navigationOptions, route);

// play "guidance will start now" audio prompt
tn::drive::models::v1::AudioRequest request;
request.request_type = tn::drive::models::v1::AudioPromptType::StartNavigation;

tn::drive::models::v1::AudioInstruction instruction;
driveSession->requestAudio(request, instruction);
playAudioInstruction(instruction);

Another example is when vehicle goes off-route (i.e. deviated from current route in navigation) or off-road (i.e. not matched to any road), you could request a Deviation or OffRoad audio prompt.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
void NavigationObserver::onNavigationStatusUpdated(const tn::drive::models::v1::NavStatus& navStatus)
{
    if (navStatus.vehicle_status == tn::drive::models::v1::NavStatus::VehicleStatus::Deviated)
    {
        // play "you are now off track" audio prompt
        tn::drive::models::v1::AudioRequest request;
        request.request_type = tn::drive::models::v1::AudioPromptType::Deviation;

        tn::drive::models::v1::AudioInstruction instruction;
        driveSession->requestAudio(request, instruction);
        playAudioInstruction(instruction);
    }
    else if (navStatus.vehicle_status == tn::drive::models::v1::NavStatus::VehicleStatus::OffRoad)
    {
        // play "please proceed to the highlighted road" audio prompt
        tn::drive::models::v1::AudioRequest request;
        request.request_type = tn::drive::models::v1::AudioPromptType::OffRoad;

        tn::drive::models::v1::AudioInstruction instruction;
        driveSession->requestAudio(request, instruction);
        playAudioInstruction(instruction);
    }
}