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 navigation service is created with both audio and navigation components enabled, after navigation starts along a route, the navigation service 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	turn right at the exit	Third phase guidance is given when vehicle is approaching the maneuver point, so it should be short and accurate.
	exit right	exit right
	turn right	turn right
	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.

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 navigation service
        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 navigation service, 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.

// 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. Navigation service 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.

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

Customize third guidance prompt content

The user could customize whether enable this feature by change the settings tn::drive::api::SettingConstants::SETTING_AUDIO_SIMPLIFY_THIRD_GUIDANCE The road name / branch name / towards name will not be provided for the third guidance of turn(except u-turn) / enter / exit / keep / continue / hookturn maneuver by default

const auto settings = tn::foundation::Settings::Builder()
    .setString(tn::drive::api::SettingConstants::SETTING_AUDIO_SIMPLIFY_THIRD_GUIDANCE, "false")
    .build();

tn::drive::NavigationServiceOptions options;
options.enable_audio = true;
options.enable_navigation = true;

const auto navigationService = tn::drive::api::NavigationServiceFactory::createNavigationService(
    options, system, settings, mapContent, directionService);

Here is the differences in the third guidance

Turn action	Simplified	Prompt content	Comment
exit roundabout	true	turn right at the exit	Two prompts are same because it's a roundabout prompt
	false	turn right at the exit
exit right	true	exit right	The next street name is removed when simplified
	false	exit right to I 405 south
turn right	true	turn right	The next street name is removed when simplified
	false	turn right to Huntington Dr
u-turn	true	make a u-turn if possible at 5th Avenue	Two prompts are same because it's a u-turn prompt
	false	make a u-turn if possible at 5th Avenue
arrival destination	true	you have reached your destination on your right	Two prompts are same because it's an arrival prompt
	false	you have reached your destination on your right

Enable traffic light prompt for navigation

The user could customize whether to enable this feature by changing the settings tn::drive::api::SettingConstants::SETTING_ENABLE_TRAFFIC_LIGHT_PROMPT. Traffic light count will be added to turn-by-turn audio by default.

const auto settings = tn::foundation::Settings::Builder()
    .setString(tn::drive::api::SettingConstants::SETTING_ENABLE_TRAFFIC_LIGHT_PROMPT, "false")
    .build();

tn::drive::NavigationServiceOptions options;
options.enable_audio = true;
options.enable_navigation = true;

const auto navigationService = tn::drive::api::NavigationServiceFactory::createNavigationService(
    options, system, settings, mapContent, directionService);

Here is the differences in the prompt

Turn action	Enable traffic light prompt	Prompt content	Comment
turn right	true	turn right at the second traffic light	normal traffic light case
	false	turn right
turn left	true	turn left at the traffic light
	false	turn left
turn right at T-intersection	true	turn right at the end of the road	Traffic light won't be given in T-intersection
	false	turn right at the end of the road
tight turn	true	turn left and then turn right at the traffic light	The tight turn traffic light will be given only when there is no traffic light or nth turn in the first half of the sentence
	false	turn left and then turn right

Request additional audio prompt for navigation

Navigation service 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.

// start a navigation session with audio component enabled at the creation of the navigation service
auto* navigationSession = navigationService->startNavigation(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;
navigationService->requestAudio(request, instruction);
// get audio prompt type for request audio
const auto prompt_type = instruction.prompt_type;
assert(prompt_type == tn::drive::models::v1::AudioPromptType::StartNavigation);
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.

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;
        navigationService->requestAudio(request, instruction);
        // get audio prompt type for request audio
        const auto prompt_type = instruction.prompt_type;
        assert(prompt_type == tn::drive::models::v1::AudioPromptType::Deviation);
        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;
        navigationService->requestAudio(request, instruction);
        // get audio prompt type for request audio
        const auto prompt_type = instruction.prompt_type;
        assert(prompt_type == tn::drive::models::v1::AudioPromptType::OffRoad);
        playAudioInstruction(instruction);
    }
}