# Command-Line Arguments for the Google Timeline Visualizer: A Complete Reference

> Explore all six command-line arguments for the Google Timeline Visualizer. Learn about input path, year selection, output filename, and more to customize your visualizations.

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

---

**The Google Timeline Visualizer accepts six command-line arguments—including required input path, optional year selection, output filename, title overlay, camera movement style, and long-trip compression level—all defined in [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) using Python's `argparse` module.**

The `mahlernim/google-timeline-visualizer` transforms Google Takeout location exports into animated travel videos through a scriptable interface. Understanding the available command-line arguments for the visualizer enables precise control over data filtering, rendering behavior, and final output presentation.

## CLI Architecture in visualizer.py

The interface is constructed using `argparse.ArgumentParser` in the main entry point. According to the source code, argument definitions reside at lines 44-53 of [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py), where each parameter is registered via `parser.add_argument` with type validation, default values, and help strings.

## Required Arguments

### --input / -i

The **input** argument specifies the path to your [`Timeline.json`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/Timeline.json) export from Google Takeout. This parameter uses a custom `existing_file` validator to ensure the file exists before execution begins. It accepts no default value and must be provided.

```bash
python visualizer.py -i /path/to/Timeline.json

```

## Output Configuration Options

### --output / -o

Defines the destination filename for the generated visualization. Defaults to `travel_history.mp4` if unspecified.

### --title / -t

Sets the text overlay displayed on every frame of the video. The default value is `"My Trips"`, but you can specify custom titles for different projects.

## Temporal and Rendering Controls

### --year / -y

Filters location history to a specific calendar year. The default uses the current year via `datetime.now().year`. This integer parameter ensures you render only relevant timeline segments.

### --camera-movement

Selects the algorithm that determines how the viewport follows your route. Available choices from the `CAMERA_MOVEMENTS` constant include:

- `fixed` – Static viewpoint
- `steady` – Smooth, conservative tracking (default)
- `dynamic` – Aggressive, responsive camera following

### --long-trip-compression

Controls animation timing for extended journeys using compression exponents defined in `COMPRESSION_EXPONENTS`. Options include:

- `off` – No compression
- `gentle` – Subtle speed adjustments
- `balanced` – Moderate compression (default)
- `strong` – Aggressive time compression for lengthy routes

## Practical Usage Examples

Combine arguments to customize your visualization pipeline:

```bash

# Basic usage with current year

python visualizer.py -i /path/to/Timeline.json

# Specific year with custom output

python visualizer.py -i Timeline.json -y 2022 -o my_2022_trip.mp4

# Dynamic camera with gentle compression

python visualizer.py -i Timeline.json --camera-movement dynamic --long-trip-compression gentle

# Custom title overlay

python visualizer.py -i Timeline.json -t "Vacation 2023"

```

## Testing and Validation

The repository includes comprehensive tests for CLI behavior. The file [`tests/test_cli_errors.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/tests/test_cli_errors.py) validates error handling for missing or malformed arguments, while [`tests/test_parser.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/tests/test_parser.py) verifies the timeline parsing logic triggered after successful argument processing. These ensure the `existing_file` validator and choice constraints function correctly across different input scenarios.

## Summary

- The **command-line interface** is defined in [`visualizer.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) using `argparse.ArgumentParser` at lines 44-53
- **Required parameter**: `--input` (`-i`) validates file existence before processing
- **Output control**: `--output` defaults to `travel_history.mp4`, `--title` defaults to `"My Trips"`
- **Temporal filtering**: `--year` defaults to the current calendar year via `datetime.now().year`
- **Camera behavior**: `--camera-movement` offers `fixed`, `steady` (default), and `dynamic` modes from `CAMERA_MOVEMENTS`
- **Compression**: `--long-trip-compression` provides four levels from `off` to `strong` via `COMPRESSION_EXPONENTS`, defaulting to `balanced`

## Frequently Asked Questions

### What is the default output filename for the generated video?

If you do not specify the `--output` or `-o` flag, the visualizer saves the rendered video as `travel_history.mp4` in the current working directory. You can override this with any valid file path ending in `.mp4`.

### How does the visualizer validate the input JSON file?

The tool uses a custom `existing_file` validator attached to the `--input` argument. This check runs immediately during argument parsing to confirm the [`Timeline.json`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/Timeline.json) path exists, preventing runtime errors from missing Google Takeout exports.

### Can I visualize location history from a specific year only?

Yes. Use the `--year` or `-y` flag followed by a four-digit integer (e.g., `-y 2022`). The default value uses `datetime.now().year` to automatically select the current calendar year if you omit this parameter.

### What is the difference between steady and dynamic camera movement?

**Steady** camera movement provides conservative, smooth viewport tracking suitable for most travel logs, while **dynamic** mode implements aggressive, responsive camera behavior that closely follows rapid location changes. The `fixed` option maintains a static viewpoint throughout the animation.