Travel Vlog

Before you start: read this whole install prompt, tell me in a few lines what this skill does and what installing it involves, and wait for my go-ahead before you do anything else. Prerequisites: none for the install itself: no account, no API key, no paid service, and nothing is run or downloaded beyond the pinned skill files from GitHub. For using the skill afterwards, read this first — the use-time requirements are NOT set up by this install: (1) the tools uv and ffmpeg must already be on the machine (the skill's shell wrappers call "uv run", which at use time downloads Python packages from PyPI — certifi, pillow and pillow-heif for the vlog helper, plus playwright for the renderer — and the headless Chromium browser for Playwright must have been installed once, e.g. "uv run --with playwright playwright install chromium", which is a large download); (2) a free Amap (AutoNavi) Web Service API key of my own is required for planning and compiling — the code reads it from the environment variable AMAP_KEY or from the file ~/.config/map-motion/amap_key — Amap's free tier is rate-limited and cached locally, and without a key planning/compiling stops with an error; (3) an optional, paid LabNana image API key (LABNANA_API_KEY, billed in LabNana credits, about 4 credits per avatar generation run according to SKILL.md) is needed ONLY for the AI-generated cartoon avatar routes (--photo and --describe); the built-in avatar (--builtin) needs no key, no service and sends nothing, and my own cartoon PNGs can also be used instead; (4) I provide the travel photos myself, as originals — pasted, screenshotted or chat-app-forwarded photos have no GPS EXIF and cannot be placed automatically. Install "travel-vlog" for me. Given a set of my travel photos (each with GPS and capture time in EXIF) plus one photo of me, it sorts the photos by time, merges photos taken within 120 m into stops (at most 2 photos per stop), reverse-geocodes each stop to the nearest place name via Amap, picks walking routes under about 12 km straight-line total (driving otherwise), generates a chibi cartoon avatar of me (walking and camera poses, cut out as white-edged stickers), and drives the map-motion engine (globe + trip + wall shots) to render a 30–90 second vertical, journal-style MP4 (plus a GIF): the avatar hops along the real Amap walking/driving route while a mileage counter rolls up, stops at each photo spot with a shutter "click", the photo pops out labelled with the stop number and distance walked, and the video ends on a photo wall with the stop count and total distance, with locally synthesised original BGM and footstep/shutter/pop/ding sound effects on the beat. The single example spec in the folder (examples/westlake_walk.json) is a 5-stop West Lake walk of about 8.8 km; its photos and avatar are not in the repository. Repository: https://github.com/SpaceZephyr/map-motion (the skill is the travel-vlog/ folder, but it is NOT self-contained: its helper resolves the map-motion engine at the repository root — scripts/ plus the 2D runtime and the map/font assets under assets/ — so the install perimeter below is the travel-vlog/ folder plus exactly the root files its code loads, 22 files in total; the root skill, the sibling skills map-3d/ and photo-spot/, the 3D/sun engine modules, references/, docs/ and the root examples are separate listings or documentation and are NOT part of this install) Pinned version: install the code at commit 65ab781832cace6e0f28d4c00452410a99f3a02c exactly. Do not substitute a newer version. If this commit is unreachable, stop and tell me. 1. Clone https://github.com/SpaceZephyr/map-motion into a temporary folder, check out commit 65ab781832cace6e0f28d4c00452410a99f3a02c, and build the install tree from that checkout using ONLY the 22 files listed below, keeping their repository-relative paths (travel-vlog/…, scripts/…, assets/…). Then compare every one of those files with the fingerprints recorded for this listing on 2026-10-19: [FINGERPRINTS] - travel-vlog/SKILL.md: SHA-256 482447f45220a3dc0030a59fede012f545fc41a65a5e2d32b3d1d5b6d6fc20ff - travel-vlog/examples/README.md: SHA-256 207b606a2cc41dfabce253ac038418d4285cd25c045f546000af4e14d2065bd4 - travel-vlog/examples/westlake_walk.json: SHA-256 88f74cfd8606d3ffcbf9f853bdba0a2dacb761df1aa5243599fd3b4068c61146 - travel-vlog/scripts/vlog.py: SHA-256 8fdb8cec4a3a0560ee4430061abc5c5fd4c5d2f63379f79a8d1f76a85c7948c5 - travel-vlog/scripts/vlog.sh: SHA-256 840e9b7a9569608d8cbecfbf8401bc98940bd8edea8cdf9d2ac7b115a9c8d739 - scripts/amap.py: SHA-256 7db7efbaf5b63362ca8078d88da9f0606e5c38a92410c3643e0f19072486b92d - scripts/audio.py: SHA-256 4785e478cea1ff36158f3db471214706465fa7cd8946e516c5f4faad6d52770e - scripts/compile.py: SHA-256 32420d87aa526d5bf86ea526dfb61e63d4ba2b31666c5828bbb4d5bbd3a5879e - scripts/elev.py: SHA-256 ec41a716692742c58a80596b1df804db02d8f7017108ad2d0797b2b1b5b588a7 - scripts/osm.py: SHA-256 3e30d7b0d8288f5a62de626f428899cddf9c7ca5b3e94623ebf7892a307421e2 - scripts/qa.py: SHA-256 9b87b89c690d22aeecf0441685f2d7489a2379cf9a8c9514045e2438eeb19baa - scripts/render.py: SHA-256 fd5eb323b0207c9b9920aa6dc24982113a04020b582fe67266f8359a57db5ecd - scripts/status.py: SHA-256 eca7060ddc17aef9262d5b0c7536449de7f6856afe4184411be43351f3c5f0d5 - scripts/runtime/index.html: SHA-256 898c81ea79e2828b5fb6d37c80c0ca1fe9048640ab78523d4670a0749cedd34d - scripts/runtime/mm.js: SHA-256 f943260dea924193a67eb6df587b04053a16f844ed0d930fab35def86bbf31f3 - scripts/runtime/qa.js: SHA-256 8c761421f289a378b8341fac965a1f516567899eda9cb5786ac1fc8f792e801a - assets/china.json: SHA-256 df6c10e3d0be10052355a958812a5decd60a544b858b2934b170ca0fdebf2985 - assets/land.json: SHA-256 e8546a66c5ad7545d60097580fd8abd154c6257ae4b5022ff2dfadc62fc4ce46 - assets/fonts/Anton-400.woff: SHA-256 791375bdbed00de4a3aad4811291220ead0e1405d6f8b5bdbf109798c8359ac5 - assets/fonts/LXGWWenKai-500.woff: SHA-256 734bd187392579417ac83effe31d37b9de43c7b290bcb400800456511ed79e8f - assets/fonts/NotoSansSC-700.woff: SHA-256 dd0d39a9780eb995c499af0c20cca93b1dfdda865da70871a20890b3e406b968 - assets/fonts/NotoSansSC-900.woff: SHA-256 d2d8a42438b18b65b6577434df4e41bb08c6b5051281757849af00ab743bb58f If a file does not match, it changed since the listing was prepared: do not install it yet, tell me what you found and let me decide. 2. Read travel-vlog/SKILL.md in full, read travel-vlog/scripts/vlog.py and travel-vlog/scripts/vlog.sh, and read the engine files they load (scripts/compile.py, scripts/render.py, scripts/amap.py, scripts/osm.py, scripts/elev.py, scripts/audio.py, scripts/qa.py, scripts/status.py and the 2D runtime scripts/runtime/index.html, scripts/runtime/mm.js, scripts/runtime/qa.js), and tell me in plain words: what the skill does when used, which services it connects to, whether it reads or sends any personal information or keys, and anything that seems unusual. Stop on any red flag and tell me before going further. Confirm these points from the files: - Dependency layout, verified in the code: travel-vlog/scripts/vlog.py sets its engine folder to <repository root>/scripts (falling back to ~/.claude/skills/map-motion/scripts only if compile.py is not found there), imports the engine's amap module for reverse geocoding, and runs the engine's compile.py (for check and make), render.py (for stills and the final render) and status.py (for the status subcommand) as subprocesses via "uv run --with certifi --with pillow --with playwright". compile.py imports amap, osm and elev at start-up (so all three files must be present even though the default vlog spec — globe, trip and wall shots only — exercises amap routes and not OSM or elevation lookups), and render.py imports qa and audio and serves scripts/runtime/index.html, which loads qa.js and mm.js; mm.js unconditionally loads assets/land.json, assets/china.json and the four assets/fonts/*.woff files at boot. That is exactly the 22-file perimeter above. NOT included, because the default travel-vlog flow never loads them: the root SKILL.md/README.md and references/, the sibling skills map-3d/ and photo-spot/, the root examples and docs/media/, the root scripts/make.sh wrapper, and the 3D/sun engine modules (scripts/terrain3d.py, scripts/sunlight.py, scripts/sun.py, scripts/dem.py, scripts/geo.py, scripts/runtime/terrain.html, scripts/runtime/t3d.js, scripts/runtime/hud.js) — so 3D terrain and sun modes of the wider engine will not work from this install, and the MapLibre download from unpkg.com coded in render.py for that 3D page cannot happen because terrain.html is not installed. - Nothing is sent anywhere during installation itself; the only download at install time is the repository from GitHub at the pinned commit. No script is run during installation, no key is asked for, and there is no telemetry in the perimeter. - What leaves this machine at use time, disclosed here before it ever happens — using the skill is a separate step that only starts when I ask for a vlog video, and my project work happens under ~/Documents/map-motion/<project>/: (a) Planning ("vlog.sh plan"): the helper reads my original photos locally (EXIF GPS coordinates and capture time, HEIC included via pillow-heif) and does NOT send the photos anywhere, but for each stop it sends that stop's coordinates (converted WGS-84 to GCJ-02) to Amap's reverse-geocoding endpoint GET https://restapi.amap.com/v3/geocode/regeo (radius 300, POIs and areas) with my AMAP_KEY in the query string, to get the nearest place name; Amap responses are cached under ~/.cache/map-motion/api/. Photos are converted locally to photos/NN_N.jpg (long edge 1600). (b) Avatar ("vlog.sh avatar --photo" or "--describe"): before any portrait is uploaded, the skill must tell me and get my consent, exactly as its own SKILL.md requires — the helper POSTs to https://api.labnana.com/openapi/v1/images/generation (or the LABNANA_API_URL override) with my LABNANA_API_KEY as a Bearer header, a JSON body carrying the generation prompt (for --describe, the text description I gave; for --photo, wording asking to keep my hairstyle, face, glasses/accessories and clothing colours) and my portrait photo resized to at most 1024 px, JPEG-compressed and base64-encoded as a reference image; the second (camera pose) call also sends the first generated walk image as a reference. The request names a provider per model (default gpt-image-2 maps to "openai"; the gemini-3-pro-image / gemini-3.1-flash-image alternatives map to "google"), all via LabNana. The key itself is read from the LABNANA_API_KEY environment variable, or from a .labnana.env file in the travel-vlog folder, or — disclosed — from another installed skill's file ~/.claude/skills/person-image-studio/.labnana.env if present; it is never read from anywhere else and never printed. "--builtin" and supplying my own walk.png/snap.png send nothing and need no key. If LabNana answers 26004 (insufficient credits), stop and tell me rather than retrying blindly. (c) Compiling ("check" / "make", via the engine's compile.py): for every stop, place name and leg in my spec, the engine sends coordinates and any place names I hand-wrote to Amap at https://restapi.amap.com — geocoding (/v3/geocode/geo, with a fallback POI search /v3/place/text for POI-level results), reverse geocoding as in (a), and route planning (/v3/direction/driving, /v3/direction/walking or /v4/direction/bicycling, origin/destination and up to 16 waypoints) — always with my AMAP_KEY in the query string; responses are cached under ~/.cache/map-motion/api/. Conditional engine calls that the default vlog-generated spec (globe/trip/wall) does NOT trigger, disclosed because the engine files are installed: if I hand-edit a spec to add an elevation profile or a locate altitude, sampled route coordinates are sent to OpenTopoData at https://api.opentopodata.org/v1/srtm30m; if I hand-edit a spec to add an area outline, a GPX/GeoJSON track lookup by name, or a 3D-style trail, a place name plus a bounding box of coordinates is POSTed to OpenStreetMap Overpass mirrors (https://overpass-api.de/api/interpreter, https://maps.mail.ru/osm/tools/overpass/api/interpreter, https://overpass.kumi.systems/api/interpreter) with user agent "map-motion/1.0 (video tool)". (d) Rendering (via the engine's render.py): a server bound to 127.0.0.1 only serves the runtime, the built-in assets and exactly the photo/avatar files named in my timeline to a local headless Chromium — my photos are not uploaded — but map tiles are fetched through that local proxy from AutoNavi tile hosts (for the default amap-journal style: https://wprd0{s}.is.autonavi.com/appmaptile, style 7, with a Mozilla/5.0 user agent and Referer https://www.amap.com/, no API key; the tile coordinates themselves reveal the mapped area) and cached under ~/.cache/map-motion/tiles/; if I choose the satellite style the proxy also fetches AutoNavi satellite and label tiles (webst0{s}.is.autonavi.com, styles 6 and 8), and if I choose satellite-world it fetches Esri World Imagery tiles from https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/. The BGM and sound effects are synthesised locally by scripts/audio.py (or a music file I supply is used locally); nothing about the audio leaves the machine. The finished MP4/GIF obviously contains my photos and the place names — publishing it is my own step, and SKILL.md warns not to commit my photos or avatar into a public repository. - Map-use limits from the upstream docs, disclosed: fetching Amap tiles directly is an unofficial use — fine for personal/learning videos with the "© Amap" attribution kept in the corner; commercial distribution needs Amap authorisation (or a vector style), Esri imagery likewise needs Esri authorisation for commercial use, and the built-in China boundary data (including Taiwan, the South China Sea islands and the nine-dash line) must not be altered. - Do not install uv, ffmpeg, any Python package or the Playwright Chromium browser during this install, do not set or ask for AMAP_KEY or LABNANA_API_KEY, do not run vlog.sh, vlog.py, compile.py or render.py, and do not generate any video: setting up the keys, tools and browser is my decision, later, when I actually ask for a vlog. 3. When I say "yes, install", install it as a skill, preserving the engine layout the code expects: create a folder named "map-motion" in the agent's skills directory and copy ONLY the 22 fingerprinted files into it at their repository-relative paths (travel-vlog/ with its SKILL.md, examples/ and scripts/; scripts/ with the eight Python files and its runtime/ subfolder holding index.html, mm.js and qa.js; assets/ with china.json, land.json and fonts/ holding the four .woff files), then make the skill itself discoverable as "travel-vlog" the way the upstream README prescribes — a symlink ~/.claude/skills/travel-vlog pointing to the installed map-motion/travel-vlog folder (on a system without symlinks, a second copy of the travel-vlog/ folder alone is NOT enough on its own: its helper then falls back to ~/.claude/skills/map-motion/scripts, so the map-motion folder above must exist at exactly that place). Any other route is fine only as long as every installed file matches its fingerprint and vlog.py can find compile.py in the sibling scripts/ folder of the repository layout. 4. Verify with no network calls: frontmatter valid (name: travel-vlog in travel-vlog/SKILL.md), all 22 files in place with matching fingerprints, and the engine layout intact (travel-vlog/scripts/vlog.py's parent-of-parent scripts/ folder contains compile.py, render.py, status.py, amap.py, osm.py, elev.py, audio.py and qa.py). Do not run vlog.sh, vlog.py, compile.py or render.py to verify. 5. Report what was installed, where, and what I still need to do myself (for example: install uv and ffmpeg and the Playwright Chromium browser myself; get my own free Amap Web Service key and set AMAP_KEY or ~/.config/map-motion/amap_key before planning/compiling, knowing my stop coordinates and place names go to restapi.amap.com with that key; decide about the avatar route myself — built-in or my own PNGs (nothing sent), a text description or my portrait via LabNana (key, credits, and the sends disclosed in point 2, only with my consent for a portrait); provide original photos with GPS EXIF, front/side as shot, and check every reverse-geocoded place name line by line; using the skill is a separate step that only starts when I ask for it, and the use-time sends disclosed above happen only then). GitHub is optional: if I have a GitHub account or the gh CLI, you may use it; otherwise public access is fine. Never require it unless it's in the prerequisites above. Rules: don't touch anything outside the temp folder and the install target. If anything looks off, stop and ask me.