Google Timeline Visualizer 딥다이브
— 내 위치 기록을 "여행 영상"으로, 그것도 폰 안에서만

1프로젝트 한 줄 요약

Timeline Visualizer가 하는 일은 한 문장으로 끝난다. 구글 지도에서 내보낸 위치 기록 파일(Timeline.json)을 넣으면, 지도 위를 작은 마커가 내가 다닌 경로를 따라 움직이는 여행 애니메이션 영상을 만들어 준다. 기간(월 범위 또는 정확한 날짜)을 고르고, 카메라 움직임을 정한 뒤 "영상 만들기"를 누르면 MP4가 저장된다. 긴 여행은 웅장하게 천천히, 짧은 출퇴근은 빠르게 — 이동 거리에 따라 재생 속도가 달라지는 게 이 영상의 매력이다.

이 프로젝트가 유독 신경 쓰는 지점은 "이 민감한 위치 데이터를 어디서 처리하느냐"다. 답은 전부 내 기기 안이다. 서버로 파일을 올리지 않고, 구글 계정에 로그인하지도 않으며, 앱은 위치 권한조차 요구하지 않는다. 내가 직접 고른 JSON 파일과 영상 파일만 읽고, 렌더링(그림 그리기)도 기기 안에서 끝낸다. 지도 배경(타일)만 지도 제공자에서 받아 온다.

가장 빠른 체험은 설치가 필요 없는 아이폰/브라우저 웹앱이다. 사파리로 아래 주소를 열고, 폰에서 내보낸 Timeline.json을 고르면 된다.

# 설치 없이 브라우저에서 (사파리 16.4+ 권장)
https://ahn-lab.org/google-timeline-visualizer/
#  → Timeline.json 선택 → 기간·카메라 고르기 → Create MP4

안드로이드에서는 저장소의 최신 릴리스에서 TimelineVisualizer-*.apk를 받아 설치한다(아직 구글 플레이 등록 전이라 "출처를 알 수 없는 앱 설치" 허용이 한 번 필요). 데스크톱에서 돌려 보고 싶다면, 이 프로젝트의 최초 원형인 파이썬 CLI visualizer.py가 그대로 남아 있다.

2왜 지금 주목받는가

비슷한 "위치 기록 시각화" 도구는 예전에도 있었다. 그런데 이 앱이 2026년 8월 GitHub 트렌딩 1위까지 오른 데는 타이밍이 결정적이었다. 세 가지가 겹쳤다.

① 구글이 타임라인을 "폰 안"으로 옮겼다 — 그래서 도구가 필요해졌다

구글은 2024년 말, 지도 타임라인을 클라우드에서 기기 저장으로 전환했다. 웹 버전 타임라인은 없어졌고, 계정에 있던 과거 기록은 최근 90일 치만 폰으로 옮겨지고 나머지는 사용자가 직접 백업하지 않으면 삭제됐다. 이제 내 위치 기록을 보려면 폰에서 직접 Timeline.json으로 내보내야 한다. "손에 JSON 파일은 생겼는데, 이걸로 뭘 하지?"라는 수요가 바로 이 시점에 폭발했고, 이 앱이 그 자리에 딱 맞아떨어졌다.

② 프라이버시가 세일즈 포인트가 됐다

위치 기록은 가장 민감한 개인정보다. "예쁜 영상 만들어 줄 테니 위치 파일 올리세요"라는 웹 서비스에 사람들이 선뜻 파일을 올릴 리 없다. 이 앱은 정반대다 — 아무것도 올리지 않는다. 구글 로그인 없음, 위치 권한 없음, 분석(애널리틱스) 없음, 광범위한 저장소 권한 없음. 첫 실행 때 "지도 타일만 지도 제공자에 요청한다"는 사실까지 설명하고 취소할 기회를 준다. 이 투명함이 신뢰를 샀다.

③ 결과물이 공유 욕구를 자극한다

기술이 아무리 좋아도 트렌딩까지 가려면 "보여 주고 싶은 결과물"이 있어야 한다. 지도 위를 마커가 흐르며 1년치 여행이 그려지는 영상은 SNS에 올리기 좋은 소재다. 긴 비행은 지구본 위 곡선(대권 경로)으로 부드럽게 이어지고, 마지막엔 전체 경로를 한 장으로 보여 주는 "여행 개요"까지 나온다. "올해의 나"를 요약하는 감성이 확산의 연료가 됐다.

3기술 스택 전체 지도

이 저장소의 가장 큰 특징은 같은 일을 하는 세 개의 구현이 한 레포에 들어 있다는 점이다. 파이썬 CLI가 최초 원형(prototype)이었고, 그 알고리즘을 안드로이드 앱(본체)과 브라우저 웹앱으로 각각 이식했다 — 그래서 셋은 "파서 → 이상치 필터 → 투영 → 카메라 → 렌더 → 인코딩"이라는 동일한 파이프라인을 공유한다. 층별로 나눠 보면 이렇다.

안드로이드 앱 (본체 · app/)

웹 · 아이폰 앱 (web/)

파이썬 CLI (원형 · visualizer.py)

4아키텍처 심화 분석

세 구현이 공유하는 파이프라인은 Timeline.json 한 덩어리를 여섯 단계로 흘려보낸다. 각 단계가 독립적이라, 한 단계(예: 이상치 필터)만 이해해도 나머지를 따로 배울 수 있다.

핵심 ① — 다형(polymorphic) 파서: 온갖 포맷을 하나로

구글의 타임라인 내보내기는 버전·기기마다 모양이 제각각이다. 그래서 파서가 여러 포맷을 모두 받아 준다 — 최신 안드로이드/iOS의 직접 배열형, 예전의 { "semanticSegments": [...] } 형태, 그리고 의미 있는 경로가 없을 때를 위한 원시 위치 신호 폴백까지. 좌표도 문자열·latLng·도(degree)·geo: URI·E7 정수(위경도에 1e7을 곱한 정수 표기)를 모두 해석하고, 국제 날짜변경선을 넘는 경로도 처리한다. 대용량 파일은 통째로 메모리에 올리지 않고 JsonReader로 스트리밍해 읽는다.

핵심 ② — 물리 기반 이상치 필터: "순간이동"만 골라 지운다

GPS 기록에는 가끔 말도 안 되는 점이 섞인다 — 서울에 있다가 1분 만에 부산을 찍고 다시 서울로 돌아오는 식이다. 이 앱의 필터는 이런 "튐(excursion)"을 물리 법칙으로 판별한다. 짧은 시간 안에, 멀리 떨어진 곳으로, 사람이 낼 수 없는 속도로 갔다가 원래 자리로 되돌아오는 점들의 무리를 찾아 통째로 제거한다. 핵심은 보수적(conservative)이라는 점 — 조금이라도 애매하면 남긴다. 원본 JSON은 절대 건드리지 않고, 몇 개를 걸렀는지 사용자에게 보고한다.

핵심 ③ — 웹 메르카토르 투영과 카메라 무빙

지구는 둥글고 화면은 평평하다. 그 간극을 메우는 게 웹 메르카토르 투영 — 구글·OSM 등 웹 지도가 쓰는 표준 방식이다. (위도, 경도)를 지도 평면의 정규화 좌표 (x, y) ∈ [0,1]로 바꾼다(위도는 ±85.05°로 제한). 그 위를 카메라가 경로를 따라가는데, 무빙 프로파일이 세 가지다 — fixed(한 줌 고정), steady(안정적, 기본값), dynamic(지역 이동을 적극적으로 따라감). 장거리 비행처럼 점이 듬성듬성한 구간은 대권(great-circle) 경로로 보간해, 목적지로 순간이동하지 않고 지구본 위 곡선으로 부드럽게 쓸고 간다.

핵심 ④ — 온디바이스 인코딩 3인방

"업로드 없음"의 약속은 결국 인코딩을 어디서 하느냐로 지켜진다. 세 구현은 각자 플랫폼의 네이티브 인코더를 직접 부른다 — 안드로이드는 MediaCodec(하드웨어 H.264) + MediaMuxer, 브라우저는 WebCodecs의 VideoEncoder + mediabunny muxer, 파이썬은 matplotlib + FFmpeg. 렌더러가 한 장 한 장 그린 프레임(캔버스/Bitmap)을 이 인코더에 흘려 넣어 MP4를 완성한다. 지도 타일은 미리 필요한 것만 계산해 받아 두고(2단계 캐시: 메모리 LRU + 디스크 PNG), 렌더링 중에는 네트워크를 다시 타지 않는다.

5디렉토리 구조 해부

한 레포 안에 세 구현이 각자의 폴더로 깔끔히 갈려 있고, 세 곳에 같은 이름의 알고리즘 모듈이 반복되는 게 눈에 띈다(예: 안드로이드 data/LocationOutlierFilter.kt ↔ 웹 src/outlier.ts).

폴더만 봐도 이 프로젝트의 규율이 보인다 — 세 구현이 알고리즘 이름을 맞춰 두고, 각각 독립 테스트를 갖추며(안드로이드 40여 개 + 웹 vitest), docs/terminology.md로 "타임라인 파일/이동 경로/영상" 같은 용어를 언어별로 못 박아 UI 문구까지 일관되게 관리한다. 개인 개발자의 앱치고 엔지니어링 기준이 상당히 높다.

6학습 포인트

여행 영상에 관심이 없더라도, 이 레포는 아래 주제들을 실전 코드 3벌(코틀린·TS·파이썬)로 비교하며 배울 수 있는 드문 교보재다.

① 위치 데이터 파싱과 좌표계

현실의 데이터는 지저분하다. E7 정수, geo: URI, latLng 문자열, semanticSegments... 하나의 파서가 이 모든 변형을 GeoPoint로 정규화하는 과정을 보며 "다형 입력을 표준형으로 흡수하는" 설계를 익힌다. 날짜변경선 처리 같은 지리 데이터 특유의 함정도 함께 배운다.

② 웹 메르카토르 투영과 지도 타일(XYZ)

웹 지도가 어떻게 둥근 지구를 평면 타일로 자르는지 — project(lat, lng)가 (x, y) ∈ [0,1]을 내놓고, 그걸 줌 레벨에 맞춰 z/x/y.png 타일 격자로 바꾸는 슬리피 맵(slippy map)의 원리를 30줄 남짓한 코드로 이해한다. 지도 앱을 만들려는 사람에게 최고의 입문 예제다.

③ 물리 기반 이상치 제거 heuristic

"통계로 이상치 제거"가 아니라 도메인 지식(사람의 최대 이동 속도)으로 판별하는 접근을 배운다. "애매하면 지우기"가 아니라 "애매하면 남기기"라는 보수적 설계가 왜 사용자 신뢰에 중요한지 — 원본을 훼손하지 않고 걸린 개수를 투명하게 보고하는 태도까지 포함해 좋은 참고가 된다.

④ 온디바이스 하드웨어 비디오 인코딩

같은 "H.264 MP4 만들기"를 두 플랫폼에서 비교할 수 있다 — 안드로이드 MediaCodec/MediaMuxer와 브라우저 WebCodecs. 특히 웹 쪽엔 H.264 코덱 문자열(avc1.42001f 등)과 레벨 계산을 해상도별로 꼼꼼히 따진 주석이 있어, 비디오 코덱의 저수준을 배우기 좋다.

⑤ 프라이버시 우선(privacy-first) 설계

"권한을 최소로, 데이터는 기기 밖으로 내보내지 않기"를 구조로 강제하는 법을 배운다. 위치 권한도, 로그인도 없이 사용자가 고른 파일만 읽고, 유일한 네트워크(지도 타일)조차 사전 고지·동의를 받는다. "프라이버시는 기능이 아니라 아키텍처 결정"이라는 걸 보여 준다.

⑥ 안드로이드 포그라운드 서비스 + 코루틴 생명주기

수십 초~수 분 걸리는 인코딩을 포그라운드 서비스로 빼서, 화면을 꺼도·앱을 나가도 진행되고 알림으로 상태를 보여 주는 패턴을 배운다. 코루틴의 구조적 취소(중간에 취소하면 미완성 파일 삭제)와 진행률·예상 시간 추정까지, 실무형 안드로이드 백그라운드 작업의 정석이다.

7시스템 요구사항

세 구현 모두 무거운 GPU가 필요 없다. 인코딩은 각 플랫폼의 기본 기능을 쓰고, 지도 배경만 인터넷이 필요하다.

8직접 해볼 수 있는 실습 과제

python visualizer.py \
  --input Timeline.json --year 2025 \
  --output travel.mp4 --title "My 2025" \
  --camera-movement steady --long-trip-compression balanced

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크