# 타임라인 비주얼라이저

[English](README.md) · [日本語](README.ja.md)

Google 지도 타임라인 내보내기 파일로 여행 경로 영상을 만드는 Android 앱입니다.
연도 또는 월 범위를 선택하고 미리 본 뒤, 공유하기 좋은 MP4로 저장할 수 있습니다.
JSON 파일과 영상 렌더링은 휴대전화 안에서 처리됩니다.

![영상 목록](play-store/assets/screenshots/ko-KR/01-videos.png)

![새 영상](play-store/assets/screenshots/ko-KR/03-selected-period.png)

## iPhone에서 사용하기

Safari에서 [iPhone 웹 앱](https://ahn-lab.org/google-timeline-visualizer/)을
여세요. 별도 앱 설치가 필요 없고 타임라인 파일은 서버로 업로드되지 않습니다.

1. Google 지도에서 **프로필 사진 → 설정 → 개인 콘텐츠 → 타임라인 데이터
   내보내기**를 선택하고 `Timeline.json`을 파일 앱에 저장합니다.
2. 웹 앱으로 돌아와 **Choose Timeline.json**을 누르고 파일을 선택합니다.
3. 월 범위 또는 정확한 날짜와 카메라 움직임을 선택하고 지도 개인정보 안내를
   확인합니다.
4. 경로를 미리 본 뒤 **Create MP4**를 누릅니다.
5. 완성된 영상을 재생하거나 공유 또는 다운로드합니다.

MP4를 만들려면 H.264 인코딩을 지원하는 Safari 16.4 이상이 필요합니다. 영상을
만드는 동안 탭을 열어 두세요. 홈 화면에 보관하려면 Safari 공유 메뉴에서
**홈 화면에 추가**를 선택합니다. 현재 웹 앱 화면은 영어로 제공됩니다.

## Android에 설치하기

아직 Google Play에는 등록되지 않았습니다. 이 저장소의
[최신 릴리스](https://github.com/mahlernim/google-timeline-visualizer/releases/latest)에서 설치하세요.

1. **Assets**에서 `TimelineVisualizer-v2.2.4.apk`를 휴대전화로 다운로드합니다.
2. 다운로드한 파일을 엽니다.
3. 설치가 차단되면 **설정**을 누르고, 사용한 브라우저 또는 파일 앱의
   **출처를 알 수 없는 앱 설치**를 허용한 뒤 다시 설치합니다.
4. 설치가 끝나면 이 권한을 다시 꺼도 됩니다.

반드시 이 저장소에서만 APK를 받으세요. Google Play 외부에서 직접 설치하기 때문에
Android가 경고를 표시할 수 있으며, 이는 정상입니다. Android 8.0 이상이 필요합니다.
이 릴리스 이후 버전은 기존 앱 위에 업데이트로 설치할 수 있습니다.

## Timeline.json 내보내기

Android에서는 Google 지도 앱이 아니라 **휴대전화 설정**에서 내보냅니다.

1. **휴대전화 설정**을 엽니다.
2. **위치 → 위치 서비스 → 타임라인**으로 이동합니다.
3. **타임라인 데이터 내보내기**를 선택하고 계속 진행합니다.
4. `Timeline.json`을 **다운로드**처럼 찾기 쉬운 폴더에 저장합니다.

타임라인 메뉴가 없거나 이름이 다르면 [Google 타임라인 도움말](https://support.google.com/maps/answer/6258979)을
확인하세요.

제조사와 Android 버전에 따라 메뉴 이름이나 위치가 조금 다를 수 있습니다. 앱의
**타임라인 파일 받기**에서 이 안내를 다시 볼 수 있고 위치 설정 화면도 열 수 있습니다.
다만 Android에는 타임라인 화면까지 바로 여는 표준 링크가 없습니다.

iPhone에서는 내보낸 JSON을
[iPhone 웹 앱](https://ahn-lab.org/google-timeline-visualizer/)에서 바로 사용할
수 있습니다. Android 앱에서 사용하려면 Android 휴대전화로 옮겨도 됩니다.

## 보이지 않는 Google 지도 타임라인 복원하기

휴대전화를 바꾸거나 Google 지도를 다시 설치한 뒤 이전 이동 기록이 보이지 않는다면,
Google 지도에 암호화된 타임라인 백업이 남아 있을 수 있습니다. 앱의 **Google 지도
타임라인 복원하기** 링크를 누르거나 [복원 안내](docs/restore-google-maps-timeline.ko.md)를
확인하세요.

먼저 Google 지도에서 이동 기록을 복원한 뒤 새로운 JSON 파일을 내보내야 합니다.
타임라인 비주얼라이저는 Google 계정이나 암호화된 백업에 접근하지 않으며 백업을
직접 복원하지 않습니다.

## 영상 만들고 공유하기

1. **영상 만들기**를 열고 **파일 선택**을 눌러 타임라인 파일을 선택합니다.
2. 월 범위를 선택하거나 며칠간의 여행에는 **정확한 날짜**를 사용합니다. 기본값은
   최신 전체 연도이며, 연도를 넘는 기간도 선택할 수 있습니다.
3. 영상에 표시할 이름과 제목 템플릿을 확인하고 기본값을 고르거나 10초부터 300초까지
   경로 재생 시간을 직접 입력합니다. `{year}`와 `{name}`을 사용할 수 있으며 입력한
   템플릿은 다음에도 유지됩니다. 60초를 넘으면 렌더링 시간과 저장공간 안내가 표시됩니다.
4. **미리보기**로 움직이는 지도를 확인합니다. 저장 영상도 같은 디자인을 사용하지만,
   지도를 먼저 준비한 뒤 안정적으로 렌더링합니다.
5. **영상 만들기**를 누릅니다. Android 10 이상에서는 `Movies/Timeline Visualizer`에
   자동으로 저장되고 Android 8과 9에서는 시스템 저장 창이 열립니다. 단계별 진행률과 예상 남은 시간이
   표시되며, 만드는 도중 취소할 수도 있습니다. 다른 앱으로 전환하거나 화면을 꺼도
   영상 만들기는 계속됩니다.
6. 완성되면 영상을 보거나 공유하고, 1080 × 1080 전체 경로 이미지를 저장하거나
   공유한 뒤 다른 영상을 만들 수 있습니다.

타임라인을 성공적으로 불러오면 저장소가 접근 권한을 유지하는 경우 다음 실행 때 같은
문서를 자동으로 다시 엽니다. 타임라인 데이터는 복사하지 않습니다. 파일이 이동되었거나
권한이 사라지면 일반 불러오기 화면으로 안전하게 돌아갑니다.

오래된 이동 경로는 위치 마커 뒤에서 점차 사라지므로 위치가 많은 타임라인도 깔끔하고
효율적으로 영상으로 만들 수 있습니다. 선택한 이동 재생이 끝나면 1.5초 동안 전체
경로로 부드럽게 축소하고, 완성된 지도를 0.5초간 보여 줍니다.

취소하면 완성되지 않은 파일은 삭제됩니다. 미리보기가 끝난 뒤 다시 누르면 처음부터
재생됩니다. Android 13 이상에서는 알림을 허용하면 앱 밖에서도 진행률을 확인하고
완성 알림을 받을 수 있습니다. 알림을 허용하지 않아도 영상 만들기는 계속됩니다.

## 만든 영상 보관하기

완성된 영상은 **내 영상** 목록에 자동으로 추가됩니다. 미리보기 이미지, 제목,
타임라인 기간, 영상 길이, 만든 날짜를 확인하고 바로 보거나 공유할 수 있습니다.
영상은 앱 안의 전체 화면 플레이어에서 재생되며 탐색, 공유, 외부 플레이어 열기를 지원합니다.
자동으로 만든 MP4는 `Movies/Timeline Visualizer`에 저장되며, 앱에는 작은 목록 정보와 미리보기 이미지만
저장합니다.

이 기능을 추가하기 전에 만든 MP4는 **영상 추가**로 가져올 수 있습니다. 여러 영상을
한 번에 선택할 수도 있습니다. 앱 밖에서 파일을 옮기거나 삭제하면 **파일을 찾을 수
없음**으로 표시되며, 필요할 때 목록에서 제거할 수 있습니다.

**목록에서 제거**는 MP4 파일을 지우지 않습니다. **영상 파일 삭제**는 별도의 확인을
거친 뒤 저장된 파일을 완전히 삭제합니다. **모두 삭제**는 확인 후 사용 가능한 영상을
모두 지웁니다. 아래 탐색 메뉴에서 **내 영상**, **영상 만들기**, **설정**으로 이동합니다.

## 영상 설정

**설정**에서 새 영상의 기본값을 정합니다. 권장 기본값은 안정적인 카메라와 균형 잡힌
장거리 압축입니다. 고정 카메라는 하나의 확대 수준을 유지하고, 동적 카메라는 주변
이동을 더 적극적으로 따라갑니다. 장거리 압축은 재생 시간만 바꾸며 경로 모양은 바꾸지
않습니다. 영상 형식은 정사각형 480p, 720p, 1080p와 세로 1080 × 1920,
가로 1920 × 1080 프리셋을 지원합니다.

타임라인 처리에는 보수적인 GPS 이상 위치 필터가 기본으로 적용됩니다. 왕복 이동이
불가능해 보이는 고립된 위치만 무시하고 그 수를 표시하며 원본 JSON 파일은 변경하지
않습니다. 선택한 파일의 모든 위치를 사용하려면 필터를 끌 수 있습니다.

영어, 한국어, 일본어, 중국어 간체와 번체, 스페인어, 프랑스어, 독일어,
브라질 포르투갈어를 지원합니다. 설정에서 지원 언어를 직접 선택하거나 시스템 기본값을
유지할 수 있으며, 설치된 버전과 빌드 코드도 확인할 수 있습니다.

장거리 비행처럼 중간 위치가 없는 구간도 대권 경로를 따라 부드럽게 보간합니다.
따라서 카메라가 목적지로 갑자기 건너뛰지 않고 중요한 장거리 이동을 따라갑니다.
가까운 거리를 이동할 때는 마커가 화면 중앙의 안정 영역 안에서 움직인 뒤 카메라가
따라갑니다. 타임라인 위치를 변경하거나 제거하지 않으면서 출퇴근 경로에서 지도가
앞뒤로 빠르게 흔들리는 현상을 줄였습니다.

## 개인정보 보호

Google 로그인, 위치 권한, 계정 권한, 분석 도구, 전체 저장공간 권한을 사용하지
않습니다. 사용자가 직접 선택한 JSON과 영상 파일만 읽습니다.

Google 로그인으로 프로필 이름을 얻을 수는 있지만 휴대전화에 저장된 타임라인 기록을
가져올 수는 없습니다. 내보내기 단계를 줄이지 못하면서 계정 권한만 추가되므로,
기본 제목에는 사용자가 수정할 수 있는 휴대전화 이름을 사용합니다.

타임라인 파일은 업로드되지 않습니다. 네트워크는 배경 지도에만 사용됩니다. CARTO에는 화면에 표시할 지도 영역의 타일 요청이
전송되지만 Timeline JSON은 업로드되지 않습니다. 첫 타임라인을 불러오기 전에 앱이
이 전송을 설명하고 취소할 수 있도록 합니다. 자세한 내용은
[개인정보 보호 안내](docs/privacy.ko.md)를 확인하세요.

## 지원 형식

- 최신 Android/iOS 타임라인 내보내기
- 이전 `semanticSegments` 형식
- 경고와 기기 내 노이즈 감소 기능을 제공하는 선택적 원시 위치 대체 방식
- 이동 경로, 활동, 방문 위치
- 문자열, `latLng`, 도(°), `geo:`, E7 좌표
- 날짜 변경선을 지나는 경로

원본 Python 데스크톱 버전도 계속 제공됩니다. 이 프로젝트는
[MIT License](LICENSE)로 배포됩니다.