Add local GraphHopper turn-by-turn prototype

[blindndangerous]

Summary

This draft PR adds a first in-app turn-by-turn routing path for Android. It uses a local GraphHopper routing service through routingProviderUrl, so guidance stays inside Soundscape instead of handing the user to another map app.

Changes included:

• route request, parsing, route following, off-route rerouting, and spoken guidance formatting
• Start Directions on Location Details, wired through SoundscapeServiceConnection into SoundscapeService
• debug-only location injection and PowerShell scripts for local GraphHopper setup and smoke testing
• unit tests, one Compose accessibility test for the Start Directions action, and developer setup docs

Why this is draft

This is not meant as a final product decision. It gives maintainers a working branch to review before we widen scope. I would like feedback on:

• whether GraphHopper is acceptable as the first self-hosted, offline-capable provider
• whether routing should stay behind build-time routingProviderUrl config or move to user or developer settings later
• route announcement wording, reroute behavior, and stop controls
• whether debug-only location injection is acceptable for local smoke tests

Authors

• blindndangerous <20344049+blindndangerous@users.noreply.github.com>: feature direction, implementation review, commits, and testing
• OpenAI Codex <codex@openai.com>: implementation assistance. Each commit includes Co-authored-by: OpenAI Codex <codex@openai.com>.

Validation

• ./gradlew.bat :app:testDebugUnitTest --tests "org.scottishtecharmy.soundscape.navigation.*" --tests "org.scottishtecharmy.soundscape.SoundscapeServiceConnectionTest" --console=plain
• ./gradlew.bat :app:assembleDebug :app:assembleDebugAndroidTest --console=plain
• Installed debug and androidTest APKs on emulator
• adb shell am instrument -w -e class org.scottishtecharmy.soundscape.LocationDetailsScreenTest org.scottishtecharmy.soundscape.test/androidx.test.runner.AndroidJUnitRunner
• ./tools/routing/run-turn-by-turn-local-smoke.ps1 -SkipBuild -EnableTalkBack

The smoke run covered GraphHopper route checks from the start point and two off-route points, route start, silent reroute, and a TalkBack-enabled emulator run.

Notes for reviewers

Local setup is documented in docs/developers/offline-turn-by-turn-routing.md. The smoke script expects GraphHopper on 127.0.0.1:8989; the app reaches the same service from the emulator with 10.0.2.2:8989 through routingProviderUrl.

[davecraig]

Blimey, thanks - we of course have some thoughts!

Our initial aim was to enable Android users to have access to Soundscape and we've still got a few things to do on that side. Routing has always been a much requested feature, but it's also one that we've shied away from. Some of the reasons against it in Soundscape include:

• Routing is a serious business. Telling a user that they should walk along certain paths/roads makes us really nervous...
• There are lots of good routing map apps out there already
• All of the current Soundscape features can work offline as well as online using our protomaps map files. We'd like to maintain that.
• We don't want to run another server as it's expensive, especially those which don't scale so well e.g. search and routing. The app must remain free to all users.
• Original Soundscape was very specifically not a turn-by-turn guidance app.
• Turn-by-turn puts the app in charge of where the user goes, but we want the user to be in charge.

Of course there are very good arguments why Soundscape should include turn-by-turn routing:

• Having all navigation in a single app is so much easier to use. Users shouldn't have to duplicate their destination setting in multiple apps just to get turn by turn routing.
• Multiple apps talking over each other massively reduces the usefulness of all of them.
• Soundscape "routes" are too hard to create. This is definitely an issue - although routes aren't turn by turn, they are one of the main uses of Soundscape to help guide users. Currently, they are hard to create independently. We have plans to improve that, and some of them come close to turn-by-turn without handing over total control to the app.

We're several months away from where we can really think about this much deeper, but I hope this gives you an idea of our thoughts. We may end up with turn-by-turn routing, but we've got to finish off a load of other stuff first - including releasing an iOS version based on our current code.

To directly answer your questions:

whether GraphHopper is acceptable as the first self-hosted, offline-capable provider

It's the obvious choice - but it wouldn't work directly with our offline map files.

whether routing should stay behind build-time routingProviderUrl config or move to user or developer settings later

If we did go with online GraphHopper routing then we'd go looking to see if we could find any free routing server that we could piggy back on, or see how much it costs to run one, or pay graphhopper.

route announcement wording, reroute behavior, and stop controls

This would come under the deeper thinking which we can do later.

whether debug-only location injection is acceptable for local smoke tests

Yes, that's fine.

In summary, this definitely isn't a NO, but it's also not a YES! Thanks for putting in the time to do this and we'd love to have a conversation with you about it. Many of the opinions expressed above and from a risk averse and sighted viewpoint and we have plenty to learn.

[blindndangerous]

Sure, glad to help out. I'll leave this as a draft for now and when/if you'd like to return to this I can return to the conversation with Codex. It was an idea I had so wanted to put Codex to the challenge and see if something could be written.