Developer information

The app is developed using Android Studio with the majority of the app code written in Kotlin.

Get started

The quickest way to get started building the app is to run Android Studio and select File/New/Project from version control from the menu. Select Git as the version control and paste in the HTTPS code link for this project from above. Click on Clone and the project will download, open and initialize ready to build.

The URL and API Key for the tile provider server (mapping tiles), search server and map extracts server are GitHub secrets, and developers have to define them locally. An example local.properties from the root directory should look something like this:

## This file must *NOT* be checked into Version Control Systems,
# as it contains information specific to your local configuration.
#
# Location of the SDK. This is only used by Gradle.
sdk.dir=/home/userName/Android/Sdk

# Tile provider URL and API key
tileProviderUrl= https://PROTOMAPS_SERVER_URL
tileProviderApiKey=XXXXXXXXXXXXXXXXXXXX

# Search provider URL and API key
searchProviderUrl=https://PHOTON_SERVER_URL
searchProviderApiKey=

# Map extract provider URL and API key
extractProviderUrl=https://EXTRACT_SERVER_URL
extractProviderApiKey=

If you would like access to the main Soundscape tile provider for development, get in touch.

App overview

  • App architecture — an introduction to the app structure, its UI screens and the foreground service that drives audio.
  • Service and DI architecture — how SoundscapeService, SoundscapeServiceConnection and the Hilt singleton graph fit together, and how the UI talks to the service via StateFlows.

Mapping and geo data

  • GeoEngine — the code that parses Mapbox Vector Tiles into Features and exposes search/traversal APIs to the rest of the app.
  • Mapping data — how we configure and use mapping data.
  • Debugging GeoJSON — a workflow for inspecting GeoJSON generated by unit tests using geojson.io.
  • Offline maps — extract generation, hosting and in-app download for users running without a network.

Audio

  • Audio engine — the C++ engine built on Oboe and Steam Audio, the JNI bridge, and the Kotlin AudioEngine interface.
  • Voice and audio menu control — voice commands and the media-key driven audio menu used when the screen is locked.
  • Search — online and offline search, the Photon server and Android system geocoder.

Translations

  • Language support — required reading for anyone adding new strings. Covers the Weblate integration.
  • Translation terminology — preferred terms (beacon, marker, route, …) for translators and contributors.

Servers and infrastructure

Build, test and CI

  • Branch strategy — which branches are active, where to send PRs, and the upcoming KMP cutover that will replace main.
  • Build types and analytics — debug / release / releaseTest, the variant-specific source sets that swap in real or no-op analytics, and the BuildConfig values read from local.properties.
  • GitHub actions — the CI workflows and the secrets they consume.
  • Unit test example — using host-side unit tests with real map data to prototype and debug geo features.

Reference

Table of contents

This site uses Just the Docs, a documentation theme for Jekyll.