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

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 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, 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 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.

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:

# 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 validates error handling for missing or malformed arguments, while 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 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 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.

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