Human voices

In this guide you will learn how to add voice instruction guidance to a simulated navigation on a route.

Setup

First, get an API key token, see the Getting Started guide.

Prerequisites

It is required that you complete the Environment Setup - Flutter Examples guide before starting this guide.

Build and run

Start a terminal/command prompt and go to the human_voices directory, within the flutter examples directory - that is the name of this example project.

Note - the gem_kit directory containing the Maps SDK for Flutter should be in the plugins directory of the example, e.g. example_pathname/plugins/gem_kit - see the environment setup guide above. Replace example_pathname with the actual example path name, such as address_search

Download project dependencies:

flutter upgrade

run the following terminal commands in the project directory, where the pubspec.yaml file is located:

flutter clean

flutter pub get

Run the example:

Web browser

flutter run

If such a question appears, select the chrome browser; in the above example, press 2.

Android

First, verify that the ANDROID_SDK_ROOT environment variable is set to the root path of your android SDK.

In android/build.gradle add the maven {} block as shown, within the allprojects {} block, for both debug and release builds, without the line numbers, those are for reference:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
           url "${rootDir}/../plugins/gem_kit/android/build"
        }
    }
}

in android/app/build.gradle within the android {} block, in the defaultConfig {} block, the android SDK version minSdk must be set as shown below.

Additionally, for release builds, in android/app/build.gradle, within the android {} block, add the buildTypes {} block as shown:

Replace example_pathname with the actual example pathname, such as center_coordinates

android {
    defaultConfig {
        applicationId "com.magiclane.gem_kit.examples.example_pathname"
        minSdk 21
        targetSdk flutter.targetSdk
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
    buildTypes {
        release {
            // TODO: Add your own signing config for the release build.
            // Signing with the debug keys for now, so `flutter run --release` works.
            minifyEnabled false
            shrinkResources false
            signingConfig signingConfigs.debug
        }
    }
}

Then build the apk:

flutter build apk --debug

or

flutter build apk --release

the apk file is located in the build/app/outputs/apk/debug or build/app/outputs/apk/release subdirectory, for debug or release build respectively, within the current project directory, such as center_coordinates

The apk file name is app-release.apk or app-debug.apk

You can copy the apk to an android device using adb, for example:

adb push app-release.apk sdcard

And then click on the apk in the file browser on the device to install and run it.

iOS

In the ios/Podfile configuration text file, at the top, set the minimum ios platform to 13 like this:

platform :ios, '13.0'

Run pod install in the [ios folder] ./ios/

Then go back to the repository root folder and type flutter build ios to build a Runner.app.

Type flutter run to build and run on an attached device.

You can open the <path/to>/ios/Runner.xcworkspace project in Xcode and execute and debug from there.

How it works

In the example project directory, such as center_coordinates, there is a text file named pubspec.yaml which contains project configuration and dependencies. The most important lines from this file are shown here:

name: center_coordinates
description: A Flutter example using Maps SDK for Flutter.

version: 1.0.0+1

environment:
  sdk: '>=3.0.5 <4.0.0'

dependencies:
  flutter:
    sdk: flutter
  gem_kit:
    path: plugins/gem_kit

  cupertino_icons: ^1.0.2

  intl: ^0.19.0
  flutter_tts: ^4.0.2

  dev_dependencies:
    flutter_test:
      sdk: flutter

    flutter_lints: ^3.0.2

# The following section is specific to Flutter packages.
flutter:
  uses-material-design: true

The project must have a name and version. The dependencies list the Flutter SDK, and the gem_kit, Maps for Flutter SDK.

The source code is in example_pathname/lib/main.dart Replace example_pathname with the actual example path name, such as center_coordinates

import 'package:gem_kit/core.dart';
import 'package:gem_kit/map.dart';
import 'package:gem_kit/navigation.dart';
import 'package:gem_kit/routing.dart';

import 'bottom_navigation_panel.dart';
import 'top_navigation_panel.dart';
import 'tts_engine.dart';
import 'utility.dart';

import 'package:flutter/material.dart' hide Route;

The dart material package is imported, as well as the required gem_kit packages.

The tts_engine (text-to-speech) is used to speak the voice instructions.

class _MyHomePageState extends State<MyHomePage> {
  late GemMapController _mapController;

  @override
  void dispose() {
    GemKit.release();
    super.dispose();
  }

  void _startSimulation() {
    final routes = _mapController.preferences.routes;

    _navigationHandler = NavigationService.startSimulation(routes.mainRoute, (type, instruction) async {
      if (type == NavigationEventType.destinationReached || type == NavigationEventType.error) {
        // If the navigation has ended or if and error occured while navigating, remove routes.
        setState(() {
          _isSimulationActive = false;
          _cancelRoute();
        });

        return;
      }
      _isSimulationActive = true;

      if (instruction != null) {
        setState(() => currentInstruction = instruction);
      }
    }, onTextToSpeechInstruction: (textInstruction) {
      // Play the text instruction;
      _ttsEngine.speakText(textInstruction);
    }, speedMultiplier: 20);

    // Set the camera to follow position.
    _mapController.startFollowingPosition();
  }
}

In the _startSimulation() function, the onTextToSpeechInstruction: receives a text instruction, and uses the text-to-speech engine to say it:

_ttsEngine.speakText(textInstruction);

Flutter Examples

Maps SDK for Flutter Examples can be downloaded or cloned with Git