## 先给结论：它解决的是“位置历史有数据，但很难做成作品”

- google-timeline-visualizer 是 mahlernim 开源的 Google Location History 可视化项目，核心输入是 Google Timeline 导出的 Timeline.json，输出是地图预览或旅行轨迹视频。
- 项目当前提供三条入口：iPhone Safari Web App、Android APK，以及桌面 Python generator；README 明确写到 iPhone Web App 不上传 Timeline 文件。
- 桌面版需要 Python 3.9+、FFmpeg 和 requirements.txt；Android 开发构建需要 JDK 17、Android SDK Platform 36、Build Tools 36.0.0。
- 短期最值得试的是桌面 Python 路径，因为命令里能直接看到 --input、--year、--camera-movement、--long-trip-compression 和 --output，最容易完成从输入到视频的闭环验收。
- 它不适合被理解成轨迹分析平台、企业定位系统或 Google 账号恢复工具；它只处理用户已经导出的 Timeline.json，不能访问 Google 账号和加密备份。

## 这个工具真正切中的问题

Google Maps Timeline 里沉淀的位置历史，平时更像一本很厚但不好翻的流水账。你可以查某一天去了哪里，也可以回看某次旅行的大致路线，但很难把一年里的移动轨迹整理成一段能检查、能导出、能保存的视频。google-timeline-visualizer 做的事情很窄：读取 Google Location History 的 Timeline.json，把时间范围、相机运动方式和长途压缩策略变成可视化轨迹，再生成视频文件。它不是用 AI 自动写旅行故事，也不是做统计报表，而是把“我去过哪里”变成一条可播放的地图动画。

这个边界反而让项目有参考价值。很多工具一碰到位置历史数据，就容易往账号连接、云端同步、社交分享和数据分析上扩展；但位置数据是非常敏感的个人数据，功能越多，用户越需要担心数据流向。README 里对 iPhone Web App 的描述很克制：用 Safari 打开 Web App，不需要安装 App，也不会上传 Timeline 文件。Android 侧则是从仓库 latest release 下载 APK，目前还没有上 Google Play；桌面端保留原始 Python generator，使用 Python 3.9+、FFmpeg 和 requirements.txt。三条路径服务的是同一个目标：让用户自己拿着导出的 Timeline.json，在本地或浏览器里完成预览和导出。

从开发者视角看，这个项目也不是单纯的“好看的地图动画”。它提供了一个个人数据工具的产品拆法：输入是本地 JSON，处理链路尽量少碰账号权限，输出是用户能直接保存的视频。它还在 README 里明确写到，每个 preview 和 exported video 都会显示 OpenStreetMap contributors 与 CARTO attribution。这不是装饰细节，而是地图类工具必须处理的合规边界。地图底图从哪里来、归因有没有显示、导出视频里是否保留归因，都会影响这个工具能不能被放心分享。

项目在 GitHub Trending 当日排到第 2 名时，已有 2,218 Stars、254 Forks，并出现 1,053 stars today 的热度信号。这个热度不一定代表它已经稳定到适合所有人长期使用，但说明它击中了一个很具体的需求：很多人有 Google Timeline 数据，却缺一个把它快速转成年度旅行视频的工具。

## 前置条件：先确认数据、系统和工具链

要跑通这个项目，第一件事不是安装依赖，而是确认你是否真的拿得到 Timeline.json。iPhone 用户的路径在 Google Maps 里：profile picture → Settings → Personal content → Export Timeline data，然后把 Timeline.json 保存到 Files。README 对 iPhone 的说明还提到，回到 Web App 后选择 Choose Timeline.json，再选择月份范围或精确日期，选择 camera movement，并确认 map privacy notice。如果希望像应用一样使用，可以通过 Safari 的 Share 菜单选择 Add to Home Screen。

Android 用户要注意一个容易踩坑的差异：README 写明 Android 上的导出入口在手机 Settings app，而不是 Google Maps。安装 App 时也不是从 Google Play 获取，而是从项目 latest release 的 Assets 下载 TimelineVisualizer-*.apk；README 特别提醒不要下载 .sha256 checksum file。由于这是直接分发 APK，Android 可能会弹出外部安装警告，需要在 Settings 里允许浏览器或文件管理器 Install unknown apps。安装完成后，建议把这个权限再关掉。这个动作很小，但对位置数据工具来说很重要：权限只在需要时打开，不要长期放着。

桌面用户的前置条件更偏工程化：Python 3.9+、FFmpeg、requirements.txt。Python 负责运行 visualizer.py，FFmpeg 负责视频编码；如果 FFmpeg 不可用，即使 Python 依赖装好了，最后也可能卡在生成视频阶段。开发者如果要构建 Android 包，还要准备 JDK 17、Android SDK Platform 36 和 Build Tools 36.0.0，并执行 Gradle 的 test、lint、assembleGithubDebug、assemblePlayDebug 任务。这里不建议普通用户一上来就走 Android 构建路径，除非你本来就有 Android SDK 环境。最快的闭环仍然是 Python generator：输入 Timeline.json，指定年份，输出 my_trip_2025.mp4。

还有一个前置问题容易被忽略：Google Maps Timeline 可能在换手机、重装 Google Maps 或重置设备后看起来丢失。README 提到，如果旧旅程消失，可能存在 encrypted Timeline backup，需要先在 Google Maps 里恢复历史，再导出新的 JSON 文件。Timeline Visualizer 不能访问 Google 账号，也不能访问加密备份；它只能处理恢复后重新导出的 JSON。这一点决定了失败排查顺序：先确认 Google Maps 里能看到历史，再导出 Timeline.json，再交给 visualizer，而不是反过来让 visualizer 替你找回旧数据。

## 最小使用路径：从 Timeline.json 到一个可检查的 MP4

![google-timeline-visuali… 执行流程](https://developer.qcloudimg.com/http-save/yehe-3825620/1c984da809b4d16687d0c6d8d082e146.png)

*图 1｜google-timeline-visuali… 的最小可执行流程*

1. 选择桌面 Python 路径作为第一次实验对象，输入文件固定为 Timeline.json，输出文件固定为 my_trip_2025.mp4，检查点是命令参数和 README 中的示例保持一致，避免一开始就混入 Android 侧载或 iPhone Web App 的浏览器变量。
2. 把 Timeline.json 放到运行 visualizer.py 的目录，目标是让 --input Timeline.json 能直接读取文件；如果文件来自 iPhone Files 或 Android Settings 导出，先确认文件名没有被系统改成 Timeline 1.json 或被压缩成其他格式。
3. 安装桌面版依赖并调用 Python generator。下面的命令来自 README 的 Desktop Python version 与 Build and test 部分，顺序覆盖依赖安装、视频生成、开发依赖安装和 pytest 验收，适合开发者先做最小闭环。

```bash
python -m pip install -r requirements.txt
python visualizer.py --input Timeline.json --year 2025 --camera-movement steady \
  --long-trip-compression balanced --output my_trip_2025.mp4
python -m pip install -r requirements-dev.txt
python -m pytest
./gradlew test lint assembleGithubDebug assemblePlayDebug
```

1. 检查输出文件 my_trip_2025.mp4，而不是只看命令是否结束。合格的第一次验收至少包括三个动作：文件存在、播放器能打开、视频内容对应 2025 年的移动轨迹；如果轨迹明显不属于目标年份，要回到 Google Timeline 导出范围和 --year 参数排查。
2. 检查地图归因是否显示。README 明确写到，每个 preview 和 exported video 都显示 OpenStreetMap contributors 与 CARTO attribution；如果导出视频缺失这部分归因，就不应该把它当成可分享成品。
3. 如果桌面路径通过，再试 Android 或 iPhone。Android 的检查点是 APK 来源必须是该仓库 latest release 的 TimelineVisualizer-*.apk，Android 版本不低于 8.0，安装后能选择 Timeline.json 并进入 Preview；iPhone 的检查点是 Safari Web App 能选择 Files 中的 Timeline.json，并且你已经确认文件不会上传。
4. 把第一次实验范围收窄到一个年份或一个较短日期区间。README 提到时长超过 60 秒会显示渲染时间和存储提醒，所以第一次不建议直接处理多年数据；先用较短范围验证 JSON、渲染、地图瓦片准备和视频保存都正常，再扩大到全年。

## 命令与配置：这里没有 Token，关键是输入、年份和输出

google-timeline-visualizer 的 README 没有给出 API Key、账号 Token、云端 endpoint 或必须填写的 .env 文件。对这类位置历史工具来说，这不是信息缺失，而是一个重要信号：它的最小运行参数集中在本地文件和渲染选项上。桌面 Python 生成器的可见配置来自命令行参数，包括 --input、--year、--camera-movement、--long-trip-compression 和 --output。下面这个配置块只记录 README 中出现过的参数名和值，用作一次本地实验的参数清单；它不是官方 .env 文件，也不表示程序会自动读取这些键。

```env
--input=Timeline.json
--year=2025
--camera-movement=steady
--long-trip-compression=balanced
--output=my_trip_2025.mp4
```

这组参数为什么重要？--input 决定数据边界，必须指向你自己导出的 Timeline.json；--year 把处理范围限制在 2025 年，能降低第一次生成失败时的排查难度；--camera-movement steady 决定镜头运动方式，适合先做稳定预览；--long-trip-compression balanced 说明长距离移动会被压缩处理，不是逐点机械播放；--output 则给出明确产物 my_trip_2025.mp4。对开发者来说，这比“点击生成视频”更容易做验收，因为每次运行都能复现同一组输入和输出。

权限配置也要分场景看。桌面 Python 路径主要是文件读取和本地视频写入权限，风险集中在 Timeline.json 放在哪里、是否被同步盘或共享目录误传。Android 路径额外涉及“安装未知应用”权限，README 建议安装完成后可以关闭该权限；这一步不影响 App 后续使用，却能减少浏览器或文件管理器继续安装未知 APK 的风险。iPhone Web App 的关键权限是 Safari 选择 Files 中的 Timeline.json，README 明确写到没有文件上传，但用户仍然应该把它当成本地敏感文件处理，不要把 Timeline.json 放进公开网盘或团队共享目录。

Android 构建命令也给了项目维护者一条检查线：./gradlew test lint assembleGithubDebug assemblePlayDebug。这里的 test 和 lint 是基础质量闸口，assembleGithubDebug 与 assemblePlayDebug 则说明项目区分 GitHub 分发和 Play 分发构建。普通用户不需要跑这条命令，但如果你准备 fork 仓库、改动 Android UI、调整隐私提示或发布自己的构建，这条命令就是比“能打开 IDE”更可靠的验收方式。Python 侧的 python -m pytest 则负责开发依赖安装后的测试检查，适合在修改 visualizer.py 或相关处理逻辑后执行。

## 工作流拆解：三条入口对应三种使用习惯

iPhone Web App 更适合只想快速试一次的用户。它的路径很短：Safari 打开 Web App，在 Google Maps 里导出 Timeline.json，保存到 Files，回到 Web App 选择 Choose Timeline.json，选择月份范围或精确日期，设置 camera movement，确认 map privacy notice。README 还提到可以用 Safari Share 菜单 Add to Home Screen。这里的优势是不用装 App，入口轻；限制是你要接受移动浏览器里的文件选择和渲染体验，长时间视频生成可能不如桌面路径可控。

Android APK 更适合经常在手机上处理 Timeline 数据的人。它要求 Android 8.0 或更新版本，安装方式是从仓库 latest release 的 Assets 下载 TimelineVisualizer-*.apk。README 特别提醒不要下载 .sha256 checksum file，因为那只是校验文件，不是安装包。Android 可能因为 APK 不来自 Google Play 而显示警告，这是直接分发 APK 的正常现象。真正需要注意的是权限收敛：只从该仓库下载 APK，只在安装时开启 Install unknown apps，装完后关掉。对于位置数据工具，这比追求安装速度更重要。

桌面 Python generator 更适合开发者、内容创作者和需要稳定复现输出的人。它依赖 Python 3.9+、FFmpeg 和 requirements.txt，调用方式清楚，输出文件名可控。你可以把 Timeline.json、命令参数和生成结果放在同一个实验目录里，方便记录哪次参数生成了哪个视频。它也更适合做失败回退：如果 python -m pytest 失败，说明开发环境或代码测试有问题；如果 pytest 通过但 visualizer.py 生成失败，就重点查输入 JSON、FFmpeg 或输出路径；如果视频生成成功但内容不对，就回到 --year、日期范围和 Timeline 导出数据排查。

这三条入口没有谁绝对更高级。Web App 解决“我不想安装”的问题，Android APK 解决“我想在手机上完成”的问题，Python generator 解决“我想可复现、可排查、可验收”的问题。对技术读者来说，第一次推荐走 Python 路径，因为你能把每个失败点落到命令、文件或依赖上；等视频产物符合预期，再决定要不要把 Web App 或 Android App 放进日常使用。

## 输出检查与失败边界

![google-timeline-visuali… 使用边界](https://developer.qcloudimg.com/http-save/yehe-3825620/96fbd2fc19483eac683ecf675b86e76b.png)

*图 2｜google-timeline-visuali… 的通过信号、权限边界与停止条件*

- 验收指标要看具体产物：桌面路径检查 my_trip_2025.mp4 是否存在、能否播放、轨迹是否对应 --year 2025，Android 和 iPhone 路径检查 Preview 是否能打开、日期范围是否正确、导出视频是否保留 OpenStreetMap contributors 与 CARTO attribution。
- 权限与隐私边界要收紧：Timeline.json 是高敏感位置历史文件，项目处理的是用户已经导出的本地文件，不应该把它上传到不明服务；Android 安装未知应用权限只在安装 TimelineVisualizer-*.apk 时打开，安装完成后应关闭。
- 数据恢复边界要说清楚：如果 Google Maps Timeline 旧旅程丢失，需要先在 Google Maps 中恢复 encrypted Timeline backup，再导出新的 JSON；Timeline Visualizer 不能访问 Google 账号，也不能读取加密备份。
- 不适合扩大使用的失败条件很明确：如果你无法确认 APK 来源、无法确认 Timeline.json 是否完整、FFmpeg 不可用，或者导出视频缺少地图归因，就不应该把它纳入稳定工作流，更不应该批量处理多年位置数据。
- 性能和存储也要纳入检查：README 提到时长超过 60 秒会显示渲染时间和存储提醒，说明长视频会带来等待时间和空间占用；第一次实验应该用一个月或一个年份的小范围，而不是直接丢入全部历史。

失败排查可以按链路拆，而不是凭感觉重试。没有 Timeline.json，先回到 Google Maps 或 Android Settings 导出；文件存在但程序读不到，检查文件名和运行目录；依赖安装失败，检查 Python 版本是否达到 3.9+，以及 FFmpeg 是否已安装；视频生成失败，先缩短年份或日期范围，再看是否是存储、编码或数据异常；视频能生成但轨迹不对，回头检查 Timeline 数据是否已经在 Google Maps 中恢复完整。这样的排查顺序能避免一个常见误判：把 Google Timeline 数据缺失当成 visualizer 的渲染问题。

还有一个容易忽略的验收点是“可分享性”。地图视频不是只要好看就能发出去，底图归因必须跟着输出走。README 明确写到 preview 和 exported video 都会显示 © OpenStreetMap contributors 和 © CARTO。如果你后续二次剪辑、压缩或裁剪视频，至少要确认归因没有被裁掉。对于个人旅行视频，这是尊重底图许可；对于开发者复用项目，这是判断工具链是否可靠的基本检查。

## 是否值得放进日常

> 今天可以试的人，是已经能导出 Google Timeline.json、愿意在本地处理位置数据、并且能准备 Python 3.9+ 与 FFmpeg 的开发者或重度 Google Maps Timeline 用户；他们可以先按 README 的 Python generator 命令生成 my_trip_2025.mp4，再用 pytest 和视频播放结果做验收。应该先观望的人，是无法确认 Timeline 数据来源、不能接受 Android 侧载 APK、或者希望工具直接读取 Google 账号并恢复历史记录的用户，因为这个项目不做账号连接和备份解密。试用时重点看三个指标：Timeline.json 是否能被稳定读取并映射到正确年份，导出视频是否能播放且保留 OpenStreetMap contributors 与 CARTO attribution，长于 60 秒的视频在设备上的渲染时间和存储占用是否可接受。

我的判断是，google-timeline-visualizer 短期更适合作为个人数据可视化和开源工具拆解样本，而不是被包装成更大的出行分析产品。它真正值得试的点在于闭环很清楚：导出 Timeline.json，选择时间范围和 camera movement，预览，生成视频，检查归因。这个闭环足够小，也足够敏感，正好能检验一个工具是否尊重用户数据边界。

如果你是内容创作者，可以把它当成年度旅行视频的生成器，但不要忽略 Timeline.json 的保管；如果你是开发者，可以从 Python generator 入手，观察 visualizer.py、requirements.txt、pytest 和 Android Gradle 构建如何组成多端项目；如果你只是想找回丢失的 Google Maps Timeline，它不是答案，你应该先按 README 指向的恢复路径在 Google Maps 里恢复历史，再导出新的 JSON。下一步动作很简单：先用一个可控年份跑出 my_trip_2025.mp4，确认视频、归因、时间范围都正确，再决定是否扩大到全年旅行记录或安装 Android APK。


google-timeline-visualizer 是 mahlernim 开源的 Google Location History 可视化项目，核心输入是 Google Timeline 导出的 Timeline.json，输出是地图预览或旅行轨迹视频。

google-timeline-visualizer如何生成旅行轨迹视频

- google-timeline-visualizer 是 mahlernim 开源的 Google Location History 可视化项目，核心输入是 Google Timeline 导出的 Timeline.json，输出是地图预览或旅行轨迹视频。 - 项目当前提供三条入口：iPhone Safari Web App、Android APK，以及

开发工具

客户端

google-timeline-visualizer是一款将Google Timeline.json位置历史转换为可播放地图轨迹视频的开源工具，提供iPhone WebApp、Android APK和桌面Python三种入口。桌面版最易上手，通过命令行参数指定输入文件、年份和输出MP4，视频保留OpenStreetMap归因。该工具专注于本地数据处理，不访问账号，适合生成年度旅行视频。

数据可视化

数据分析

数据恢复

文件处理

代码解释

数据流

Android

Python

GitHub

JSON

腾讯云BI特惠9.9元起！


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

google-timeline-visualizer是一款将Google Timeline.json位置历史转换为可播放地图轨迹视频的开源工具，提供iPhone WebApp、Android APK和桌面Python三种入口。桌面版最易上手，通过命令行参数指定输入文件、年份和输出MP4，视频保留OpenStreetMa...

google-timeline-visualizer如何生成旅行轨迹视频-腾讯云开发者社区-腾讯云

google-timeline-visualizer如何生成旅行轨迹视频

google-timeline-visualizer如何生成旅行轨迹视频

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐