Primary question: Can a client-side renderer reliably turn your raw Timeline export into an MP4 you would actually share?
RepoDaily adoption score
RepoDaily rates this as 89/100 (strong) for adoption: evidence, installation path, production risk, differentiation, license clarity, and AI/agent fit are scored from the article sources and adoption notes.
4 source(s) across 4 source category/categories, plus a RepoDaily-specific evidence module when available.
7 workflow step(s), 5 next-action step(s), and 0 command/install signal(s) were detected.
Trending momentum is +441 stars, with maintenance/release/issue signals counted when present.
Risk is marked medium, with 6 security note(s) and 4 explicit skip condition(s).
3 opportunity lens item(s), 4 alternative(s), and 4 type-specific section(s) support differentiation.
License source or license wording is present.
4 AI/agent-related signal(s) were detected in the article text and metadata.
Project overview
google-timeline-visualizer is a Kotlin Android application that turns Google's Location History export — a Timeline.json file — into an animated travel video. You pick a month range or exact dates, preview the Journey, and produce an MP4 ready to watch or share. The repo gained 441 stars in the trending period (rank 10 on 2026-08-23), which is notable for an app that is not on Google Play: Android users sideload a TimelineVisualizer-*.apk from GitHub Releases, while iPhone users open a hosted web app in Safari. The project is MIT licensed (Copyright (c) 2025 mahlernim) and requires Android 8.0 or newer.
The iPhone path is the most interesting privacy story in the README. The web app at ahn-lab.org/google-timeline-visualizer has no install step and, per the README, no Timeline file is uploaded. You export Timeline.json from Google Maps (profile picture → Settings → Personal content → Export Timeline data), select it in Safari, confirm a map privacy notice, and the MP4 is created in the browser. The constraints are explicit: Safari 16.4 or newer with H.264 encoding support, and the tab must stay open while the video is created.
The changelog shows unusually disciplined engineering for a personal project. Version 2.2.12 fixed the renderer to draw every map tile intersecting portrait and landscape export frames instead of truncating the visible grid, with regression coverage for high-resolution grids requiring more than 36 tiles. Version 2.2.11 computes the remaining-time estimate from recent journey-frame throughput and hides it during map preparation and unstable speeds, using one estimator for both the in-app progress tray and the foreground notification. Version 2.2.10 moved settings, video-export state, and the creations list behind lifecycle-aware ViewModels and made the desktop CLI reject missing input files or an unavailable FFmpeg before parsing.
Data handling is conservative. After a successful import, 2.2.9 stores normalized semantic and raw-signal points in a compact versioned app-private cache that opens only when the source URI, size, and modification time still match; if the cache is missing, stale, incompatible, or damaged, the app falls back to the original JSON. Before encoding begins, 2.2.7 prepares every tile used by every frame and the final overview with four bounded workers, retries transient failures once, and stops with a localized connection message rather than silently producing a video with missing map areas.
Scope is honestly bounded. The app cannot restore Timeline history that disappeared after a phone change or Google Maps reinstall — it links to its own restoration guide (docs/restore-google-maps-timeline.md) and states plainly that it cannot access your Google account or encrypted backup. It also lands in RepoDaily's AI model / Agent framework category even though it is really a personal-data media renderer; the mislabel says more about trending classification than about the code.
Why it is trending now
- Google moved Android Timeline export out of Maps into phone Settings (Location → Location services → Timeline → Export Timeline data), making the JSON file a manual ritual — and a renderer that turns that file into a shareable MP4 rides directly on that friction.
- Client-side processing: the README states the iPhone web app uploads no Timeline file, and Android keeps normalized points in the app-private cache.
- Dual delivery without a store listing: sideloaded APK on Android 8.0+, hosted Safari web client on iPhone (Safari 16.4+, H.264).
- A dense run of focused releases — 2.2.5 through 2.2.13, Android version codes 25–31 — each pairing a user-visible fix (truncated tiles, stuck notifications, misleading remaining-time estimates) with tests.
- Pure word-of-mouth distribution: 441 period stars with no Play Store presence, no homepage, and no declared topics — discovery runs only through GitHub and the README's web app link.
Problem it solves
- Google Maps shows your history but does not export an animated, shareable year-in-travel video from it.
- Upload-based visualizers ask you to hand years of precise locations to someone else's server.
- Trip selection is awkward: ranges cross year boundaries, and a trip lasting a few days needs exact dates rather than a month view.
- Portrait and landscape frames can silently truncate the visible tile grid — exactly the bug 2.2.12 fixed for grids requiring more than 36 tiles.
- Long renders without honest feedback: 2.2.11 deliberately hides the remaining-time estimate during map preparation and materially unstable throughput instead of showing a number that lies.
- Network hiccups mid-render would otherwise leave blank map patches; 2.2.7 stops with a localized connection message rather than shipping a broken MP4.
How it works
- Export the data. Android: Phone Settings → Location → Location services → Timeline → Export Timeline data → Continue, saving Timeline.json to Downloads. iPhone: Google Maps → profile picture → Settings → Personal content → Export Timeline data, saved in Files.
- Load it. Android app: Create video → Choose file. iPhone: open the web app in Safari and select Choose Timeline.json.
- Pick a range: a month range, or Exact dates for a trip of a few days. The latest full year is selected by default, and ranges may cross year boundaries.
- Set preferences: camera movement and the map privacy notice on the web; distance unit on Android — Automatic resolves from the device region, with Kilometers/Miles overrides, and kilometers are preserved internally with only user-facing distances converted.
- Preview the Journey, then Create MP4. Android renders behind a foreground notification, and the completed Video ready tray clears after you watch or share the matching video (2.2.8).
- Tile preparation runs first: every tile used by every frame and the overview is fetched by four bounded workers with one retry for transient failures, before encoding starts.
- The finished MP4 lands in My videos; an Unreleased changelog entry notes the resolved video title will be embedded in exported MP4 metadata for media players and galleries.
The 20-minute hands-on path
- Fastest trial: Safari on iOS — open ahn-lab.org/google-timeline-visualizer, choose Timeline.json, pick a month range, confirm the map privacy notice, then Create MP4. No install, no upload.
- Android path: download TimelineVisualizer-*.apk from the repo's latest GitHub release (the README says not to download the .sha256 file), allow Install unknown apps for your browser or file manager, install, then revoke that permission; the README notes Android's warning is expected for a directly distributed APK.
- Requires Android 8.0 or newer, and future releases install over the current one.
- If the Timeline menu is missing, the README points to Google's Timeline Help (support.google.com/maps/answer/6258979); the in-app Get Timeline file screen shows the export steps and can open Location settings, since Android exposes no standard link to the Timeline page.
- Budget one short exact-date trip first: fewer tiles, faster encode, and it exercises the same pipeline as a full-year render.
What the changelog reveals about the internals
The renderer splits into a preprocessing cache, a tile layer, and an encode stage. Version 2.2.9 stores normalized semantic and raw-signal points in a compact versioned cache opened only when the source URI, size, and modification time still match; a manually selected file is always reprocessed so users can force a refresh, and any stale or damaged cache falls back safely to the original JSON.
The tile layer is defensive by design: 2.2.7 pre-fetches every tile needed by every video frame plus the final overview before encoding, uses unique atomic cache writes, preserves export cancellation, and caps concurrency at four bounded workers with a single retry for transient failures. 2.2.12 redefined the visible grid so every tile intersecting portrait and landscape frames is rendered, backed by regression tests for high-resolution grids above 36 tiles.
UI state is lifecycle-aware: 2.2.10 moved settings, video-export state, and the creations list behind ViewModels and replaced the thumbnail-generation counter with structured coroutine cancellation while keeping the stable row identity guard. Errors are typed — Timeline parsing and no-data cases raise instead of terminating.
There is also a desktop CLI sharing parsing code with the app; since 2.2.10 it rejects missing input files and an unavailable FFmpeg before parsing or frame preparation, and its process-lifetime tile cache is documented. A validate.yml GitHub Actions badge marks the build check.
Maintenance signals
Release hygiene is strong: every entry from 2.2.6 through 2.2.12 pins an explicit Android version code (25 through 31) and version name, fixes ship with regression coverage, and the Unreleased section already tracks the next change — embedding the resolved video title in MP4 metadata. 2.2.13 fixed the video-generation notification lingering in the system tray after the user tapped Done.
Docs are trilingual — the README links README.ko.md and README.ja.md — and edge cases get dedicated pages such as docs/restore-google-maps-timeline.md for history lost to a phone change or Google Maps reinstall.
The risk side: copyright is held by a single author (mahlernim, 2025), there is no homepage or declared topics, and Android distribution is sideload-only, so users must check GitHub releases by hand.
Upstream exposure sits with Google: the export path lives in phone Settings on Android, menu names vary by device, and the README works around this with in-app instructions rather than a deep link.
Distribution and platform constraints
- Android: not on Google Play; the APK comes only from this repository's latest release, and Android will warn about installs outside Play — the README says that warning is expected.
- iPhone: no install at all — the Safari web app can be pinned via Share → Add to Home Screen.
- Web encode requires Safari 16.4 or newer with H.264 support; the tab must stay open while the MP4 is created.
- Android minimum is 8.0+ per the README badge.
- The README's privacy claim is that no Timeline file is uploaded; the MP4 is created inside the tab, and on Android imported points live in the app-private cache.
Who should pay attention?
Good fit if
- Android 8.0+ users who already export Timeline.json and want an offline-capable renderer.
- iPhone users on Safari 16.4+ who want the result without installing anything.
- Anyone rebuilding lost history: the app's Restore Google Maps Timeline link and its restoration guide cover the case where older trips disappeared after a device change.
- Kotlin developers studying lifecycle-aware ViewModels, structured coroutine cancellation, and atomic cache writes on a small, readable codebase.
Skip for now if
- Anyone who wants Play Store auto-updates — this is a sideloaded APK you update by hand.
- Browsers without H.264 encoding: the web app's MP4 creation will not run.
- Users expecting data recovery: the app cannot access your Google account or encrypted Timeline backup.
- Anyone uncomfortable granting a browser or file manager temporary Install unknown apps permission.
Risks and cautions
Well-engineered and MIT licensed, but a single maintainer, sideload-only Android distribution outside Play review, and dependence on Google's export format and live map tiles.
- The Android release ships as a directly distributed APK; Android itself warns about apps installed outside Google Play.
- Copyright (c) 2025 mahlernim indicates one author; no homepage, no declared topics, no listed team.
- The export flow depends on Google's menus, which the README says can vary by phone, with Google's help doc as the fallback.
- Rendering depends on network tile fetches; 2.2.7 deliberately fails with a localized connection message rather than producing partial maps.
- The README states the iPhone web app uploads no Timeline file; encoding happens in Safari.
- Android keeps imported points in the app-private cache, opened only when the source URI, size, and modification time still match.
- The web app requires confirming a map privacy notice before video creation.
- APK provenance rule from the README: only download from this repository, and do not download the .sha256 file.
- MIT License (Copyright (c) 2025 mahlernim) allows forks and commercial redistribution with the notice retained.
- The app cannot access your Google account or encrypted backup; Timeline restoration must happen inside Google Maps first.
Alternatives to compare
| Approach | When to use | Trade-off |
|---|---|---|
theopolisme/location-history-visualizer | You want a zoomable heatmap of your full Location History takeout instead of an animated trip MP4 | Free, open source, self-hosted |
Google Maps built-in Timeline | You just need to browse past trips on a map, with no video export | Free with a Google account |
Google Earth Studio | You need cinematic camera choreography and can feed it your own geodata | Free with a Google account; access on request |
Screen-recording a Maps playback | A one-off recap clip where manual effort beats installing anything | Free, entirely manual |
What this trend reveals
A store-distributed fork
The README says the app is not yet on Google Play, and the MIT license permits derivative distribution with notice. A maintained Play listing would remove the project's biggest adoption friction without changing its intent.
Publish a signed build to an internal-test track and compare installs against the GitHub release download count.
An analysis layer on the versioned cache
2.2.9 already persists normalized semantic and raw-signal points locally, and 2.2.5 added distance units resolved from device region. Trip counting or city summaries could read that same cache without touching the export format.
Prototype a monthly trip-count summary over the cached normalized points and diff it against a hand-checked month.
Documented desktop parity
The desktop CLI already rejects missing input and an unavailable FFmpeg before parsing, per 2.2.10. A documented desktop release would serve users on neither Android 8.0+ nor Safari 16.4.
Run the CLI over a full-year Timeline.json and compare its MP4 against the Android app's output frame-for-frame.
RepoDaily verdict
A genuinely useful niche tool with above-average engineering for its size: versioned caches, pre-fetched tiles, typed parsing errors, and honest failure modes are all visible in the changelog, and the privacy posture — the file never leaves the device — is stated and consistent with the architecture. The costs are real too: sideload-only Android distribution, a single maintainer, and total dependence on Google keeping the Timeline export alive. Start with one short trip; if the MP4 looks good, a full year takes minutes more.