Google Timeline Visualizer: Web vs. Python CLI Implementations Explained

The Google Timeline Visualizer is implemented in two forms—a TypeScript/Vite browser application for interactive map rendering with HTML5 Canvas, and a Python CLI tool that uses Matplotlib and ffmpeg for automated video generation from Google Takeout data.

Both implementations transform Google Location History exports into animated travel videos, but they serve different use cases. The Web visualizer emphasizes interactivity and quick iteration, while the Python CLI visualizer prioritizes batch processing and higher-quality output encoding. This article breaks down the architecture, entry points, and rendering pipelines of each implementation in the mahlernim/google-timeline-visualizer repository.

---

The Two Implementations of Google Timeline Visualizer

Web Visualizer: TypeScript, Vite, and HTML Canvas

The browser-based implementation loads a Timeline.json file directly in the browser, renders an interactive map, and exports a preview-ready MP4 video.

Entry point: [web/src/main.ts](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/main.ts)

The web stack handles three core responsibilities:

• Data parsing – web/src/timeline.ts extracts GPS points from Google Takeout exports
• Rendering – web/src/renderer.ts draws map tiles and trails using 2-D Canvas APIs
• Video export – web/src/video.ts coordinates the MediaRecorder/WebCodecs pipeline

Map tiles are fetched from CARTO/OpenStreetMap on-the-fly. The export process leverages browser-native APIs for encoding, with a fallback MP4 encoder for broader compatibility.

Programmatic video export example:

import { createJourneyMp4 } from './video';

// After parsing Timeline.json into a PreparedJourney:
const journey = await getPreparedJourney();
await createJourneyMp4(canvas, journey, {
  durationSeconds: 30,
  format: videoFormatByKey('720p'),   // from VIDEO_FORMATS
  overlay: { title: 'My 2023 Trips', periodLabel: 'Jan – Mar 2023' },
  onProgress: (frac) => console.log(`Export ${Math.round(frac * 100)}%`),
});

---

Python CLI Visualizer: Matplotlib and ffmpeg Pipeline

The command-line implementation provides fully automated processing with higher-quality encoding through external tools.

Entry point: [visualizer.py](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py)

The Python pipeline executes in discrete stages:

1. Parse Timeline.json via extract_timeline_points
2. Filter GPS outliers using filter_location_outliers
3. Compute camera movement with build_camera_track
4. Render frames through Matplotlib's animation framework
5. Encode final MP4 via ffmpeg

Map tiles are retrieved with fetch_tile_img / get_map_image and composited using Pillow.

Basic CLI usage:

python visualizer.py \
  --input path/to/Timeline.json \
  --year 2023 \
  --duration 45 \
  --camera-movement dynamic \
  --aspect-ratio portrait \
  --resolution 1080 \
  --title "My 2023 Adventures"

Advanced filtering and preset options are available through --help and the build_argument_parser function.

---

Shared Core Algorithms Between Implementations

Despite different rendering targets, both implementations share identical data-processing logic:

Algorithm	Python Location	TypeScript Location	Purpose
Timeline parsing	extract_timeline_points in visualizer.py	web/src/timeline.ts	Extract GPS coordinates from Google Takeout JSON
Outlier filtering	filter_location_outliers in visualizer.py	web/src/outlier.ts	Remove GPS noise and spurious jumps
Camera tracking	build_camera_track in visualizer.py	web/src/camera.ts	Generate smooth pan/zoom trajectories
Preset encoding	encode_preset / decode_preset in visualizer.py	web/src/preset-link.ts	Serialize/deserialize visualization parameters as shareable tokens

This parity ensures consistent visual output whether you're iterating in the browser or processing files on a server.

---

Rendering Pipeline Differences

The implementations diverge at the final output stage:

Aspect	Web Visualizer	Python CLI Visualizer
Graphics API	HTML5 2-D Canvas	Matplotlib + Pillow
Map tile source	CARTO (fetched via fetch)	Direct HTTP requests in fetch_tile_img
Video encoding	MediaRecorder / WebCodecs / fallback MP4 encoder	ffmpeg subprocess
Frame generation	Real-time canvas draws	Pre-rendered Matplotlib animation
Primary use case	Interactive exploration, quick previews	Production-quality batch exports

---

Key Source Files Reference

Implementation	Critical Files	Description
Web	web/src/main.ts, web/src/renderer.ts, web/src/video.ts	UI initialization, canvas rendering, video export orchestration
Python CLI	visualizer.py	Complete pipeline including argument parsing, tile fetching, and MP4 generation
Shared logic	visualizer.py (reference) + web/src/*.ts ports	Data processing algorithms maintained in parallel

---

Summary

• The Google Timeline Visualizer ships as two complete implementations: a TypeScript/Vite browser app and a Python CLI tool
• Both share core algorithms for parsing Google Takeout data, filtering GPS outliers, and building camera tracks
• The Web version excels at rapid iteration with interactive canvas rendering and browser-based export
• The Python version delivers higher-fidelity output through Matplotlib and ffmpeg for automated workflows
• Entry points are web/src/main.ts and visualizer.py respectively, with algorithmic parity maintained across TypeScript and Python ports

---

Frequently Asked Questions

What file formats does the Google Timeline Visualizer accept?

The visualizer accepts Google Takeout exports as Timeline.json files. This is the standard JSON format provided by Google's Location History download. Both the Web and Python implementations parse this format using equivalent extract_timeline_points functions.

Can I use the Python CLI without installing a browser?

Yes. The Python CLI implementation is entirely self-contained. It fetches map tiles via HTTP requests, renders frames using Matplotlib and Pillow, and encodes video through ffmpeg—all without any browser dependencies.

How does preset sharing work between the Web and CLI versions?

Both implementations use token-based preset encoding. The encode_preset and decode_preset functions in visualizer.py and the corresponding logic in web/src/preset-link.ts ensure that visualization parameters (camera movement, duration, overlays) can be serialized and shared across platforms.

Which implementation produces higher-quality video?

The Python CLI version typically produces higher-quality output because it uses ffmpeg for final encoding rather than browser-based MediaRecorder APIs. The Web version optimizes for speed and convenience, while the CLI version prioritizes encoding fidelity and batch processing capabilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}