# Google Timeline Visualizer: Web vs. Python CLI Implementations Explained

> Explore Google Timeline Visualizer implementations: a web app for interactive maps and a Python CLI for automated video generation from your Google Takeout data. Compare both.

- Repository: [mahlernim/google-timeline-visualizer](https://github.com/mahlernim/google-timeline-visualizer)
- Tags: comparison
- Published: 2026-08-23

---

**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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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)](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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/timeline.ts) extracts GPS points from Google Takeout exports
- **Rendering** – [`web/src/renderer.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/renderer.ts) draws map tiles and trails using 2-D Canvas APIs
- **Video export** – [`web/src/video.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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:**

```typescript
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)](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py)

The Python pipeline executes in discrete stages:

1. Parse [`Timeline.json`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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:**

```bash
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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) | [`web/src/timeline.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/timeline.ts) | Extract GPS coordinates from Google Takeout JSON |
| Outlier filtering | `filter_location_outliers` in [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) | [`web/src/outlier.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/outlier.ts) | Remove GPS noise and spurious jumps |
| Camera tracking | `build_camera_track` in [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) | [`web/src/camera.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/camera.ts) | Generate smooth pan/zoom trajectories |
| Preset encoding | `encode_preset` / `decode_preset` in [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) | [`web/src/preset-link.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/main.ts), [`web/src/renderer.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/renderer.ts), [`web/src/video.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/video.ts) | UI initialization, canvas rendering, video export orchestration |
| **Python CLI** | [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) | Complete pipeline including argument parsing, tile fetching, and MP4 generation |
| **Shared logic** | [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/main.ts) and [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) and the corresponding logic in [`web/src/preset-link.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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.