Đây là link MCP của Nexus Map (trước đây Map Video Studio, https://map.nexusone.vn/mcp): công cụ dựng video bản đồ bất động sản, hạ tầng Việt Nam. ## Người dùng nhờ bạn cài MCP này? Làm như sau Tên máy chủ: nexus-map (máy đã cài với tên cũ map-video thì dùng luôn, không cài thêm). Gói npm nay là nexus-map-mcp; máy đang chạy gói cũ map-video-studio-mcp vẫn dùng được nhưng không còn cập nhật, gỡ rồi cài lại bằng lệnh dưới đây. Không cần khoá, không cần đăng nhập. Chọn một cách dưới đây, chạy đúng một lệnh. 1. Bạn chạy được lệnh trên máy người dùng (Claude Code, Codex, Gemini CLI, Cursor, Windsurf...): cài **bản chạy trên máy**, đủ 15 công cụ, xuất được MP4. Cần Node 22 trở lên (kiểm bằng `node -v`) và Chrome, Edge hoặc Chromium (của Playwright cũng được) đã cài. Thiếu Node 22 thì xuống bước 2. - Claude Code, macOS, Linux: `claude mcp add -s user nexus-map -- npx -y nexus-map-mcp@latest` - Claude Code, Windows, chạy lệnh qua Git Bash (mặc định của Claude Code trên Windows): `MSYS_NO_PATHCONV=1 claude mcp add -s user nexus-map -- cmd /c npx -y nexus-map-mcp@latest` Thiếu `MSYS_NO_PATHCONV=1` thì Git Bash đổi `/c` thành `C:/`, lệnh vẫn báo Added nhưng máy chủ không chạy. - Claude Code, Windows, PowerShell hoặc cmd: `claude mcp add -s user nexus-map -- cmd /c npx -y nexus-map-mcp@latest` - Codex: `codex mcp add nexus-map -- npx -y nexus-map-mcp@latest` - Gemini CLI: `gemini mcp add -s user nexus-map npx -y nexus-map-mcp@latest` - Ứng dụng cấu hình bằng file JSON (Cursor `~/.cursor/mcp.json`, Windsurf, Claude Desktop `claude_desktop_config.json`): thêm vào `mcpServers` `"nexus-map": { "command": "npx", "args": ["-y", "nexus-map-mcp@latest"] }` (Windows: `"command": "cmd", "args": ["/c", "npx", "-y", "nexus-map-mcp@latest"]`) 2. Không có Node 22, hoặc ứng dụng chỉ nhận MCP qua URL: cài **bản từ xa** (7 công cụ, viết và kiểm kịch bản; người dùng tự xuất video trên web). - Claude Code: `claude mcp add -s user --transport http nexus-map https://map.nexusone.vn/mcp` - Codex: `codex mcp add nexus-map --url https://map.nexusone.vn/mcp` - Gemini CLI: `gemini mcp add -s user -t http nexus-map https://map.nexusone.vn/mcp` - File JSON: `"nexus-map": { "url": "https://map.nexusone.vn/mcp" }` 3. Bạn không chạy được lệnh (Claude trên web, Claude Desktop, ChatGPT): hướng dẫn người dùng tự thêm. Claude: Settings, Connectors, Add custom connector, dán https://map.nexusone.vn/mcp. ChatGPT: bật Developer mode trong Settings rồi thêm connector với URL trên. 4. Kiểm ngay: Claude Code chạy `claude mcp get nexus-map`, phải thấy `Connected` và Args là `/c npx -y nexus-map-mcp@latest` (Windows) hoặc `-y nexus-map-mcp@latest`. Lần đầu có thể báo hết giờ vì npx đang tải gói: chờ nửa phút rồi kiểm lại. Args có `C:/` hay cài sai thì gỡ (`claude mcp remove nexus-map -s user`) rồi cài lại đúng lệnh. 5. Cài xong: bảo người dùng mở phiên mới hoặc tải lại máy chủ MCP (Claude Code: thoát rồi mở lại `claude`) để công cụ hiện ra; trong phiên đang cài thì công cụ chưa có, chỉ kiểm được bằng bước 4. Sang phiên mới thì gọi `get_guide` và làm theo. Báo người dùng đã cài bản nào (15 hay 7 công cụ), mời họ dán lời đọc hoặc bài báo kèm tên, địa chỉ dự án. Nhắc người dùng **tự gửi toạ độ vị trí dự án** (dự án mới thường không có hoặc lệch trên bản đồ mở), và chỉ cách lấy: Google Maps trên máy tính: nhấp chuột phải đúng chỗ dự án, dòng đầu là toạ độ (vd 10.7215, 106.7020), bấm vào là chép. Trên điện thoại: nhấn giữ đúng chỗ dự án để thả ghim, toạ độ hiện ở ô tìm kiếm (Android) hoặc trong thẻ kéo lên ở dưới (iPhone), chạm để chép. Lần đầu chạy bản trên máy, npx tải gói mất khoảng nửa phút. Không cài được MCP thì vẫn làm được: đọc hết tài liệu dưới đây rồi viết file kịch bản JSON theo đúng schema, người dùng mở file trên https://map.nexusone.vn để xuất video. # Nexus Map: tài liệu đầy đủ cho AI > Một file duy nhất, đọc hết là viết được kịch bản video bản đồ cho Nexus Map (https://map.nexusone.vn, trước đây tên Map Video Studio). File này sinh tự động từ tài liệu trong repo, không sửa tay. ## Dùng file này thế nào Dành cho AI không cài được MCP (ChatGPT, Gemini, Claude trên web...). Agent có MCP thì xem phần "Công cụ MCP" bên dưới, quy trình giống nhau, chỉ khác chỗ lấy toạ độ. 1. Người dùng đưa lời đọc hoặc bài báo. 2. Hỏi lại những gì còn thiếu: khổ video, độ dài, toạ độ dự án và các điểm cần chấm. 3. Viết kịch bản JSON theo schema bên dưới, trả cho người dùng trong một khối code. 4. Người dùng mở https://map.nexusone.vn, vào tab **JSON**, dán, bấm **Áp dụng JSON**. Hoặc lưu thành file `.json` rồi bấm **Mở dự án**. 5. Web dựng hình. Người dùng xem lại, chỉnh, rồi tự bấm xuất video. AI không xuất video. ### Lấy toạ độ khi không có MCP - Không tự nghĩ ra toạ độ từ trí nhớ. Hỏi người dùng. - Cách người dùng lấy toạ độ nhanh: trên Google Maps, bấm chuột phải vào điểm, bấm dòng số đầu tiên để chép. Google Maps chép theo thứ tự vĩ độ trước, kinh độ sau (vd `10.7725, 106.6980`), còn kịch bản dùng `[kinh độ, vĩ độ]`, nên phải đảo lại thành `[106.6980, 10.7725]`. - Tuyến có trong danh sách tuyến có sẵn (cuối file): ghi `"preset": "", "points": []`. Web tự nạp hình dạng. - Vùng hành chính (quận, phường) có trong danh sách vùng có sẵn (cuối file): ghi `"preset": "", "points": []` trong `zones[]`. Không tự vẽ ranh quận. - Đường có tên trên OpenStreetMap nhưng không có trong danh sách: ghi `"osm": "", "points": []`. Khi mở file, web tự tìm con đường đó quanh tâm keyframe camera đầu tiên, nên keyframe đầu phải đặt gần con đường. - Tuyến chỉ có trên giấy: xin người dùng vài điểm dọc tuyến, đặt `approx: true` và ghi chữ "minh hoạ" trong `hud.disclaimer`. ### Tự soát trước khi đưa file Không có `validate_scene` thì tự soát: - JSON hợp lệ: không có chú thích, không có dấu phẩy thừa cuối mảng. - Có `"version": 1`, có `camera`, keyframe đầu có `lng`, `lat`. - Toạ độ dạng `[lng, lat]`: lng từ 102 đến 110, lat từ 8 đến 24 (Việt Nam). - Có tuyến `approx` hoặc `kind: "planned"` thì `hud.disclaimer` có chữ "minh hoạ". - Chữ hiển thị không có dấu chấm giữa (U+00B7), gạch dài (U+2014), gạch ngang vừa (U+2013). - Caption không chồng thời gian. `hook` khoảng 20 ký tự trở xuống, `sub` khoảng 100 ký tự trở xuống. - Báo người dùng (trong lời nhắn, không ghi lên hình) chỗ nào là vị trí ước hoặc tuyến minh hoạ để họ tự kiểm. ## Nexus Map: từ lời đọc tới video bản đồ Nexus Map (https://map.nexusone.vn, trước đây tên Map Video Studio) dựng video bản đồ từ một file JSON gọi là **kịch bản** (schema v1). Việc của agent: đọc lời đọc hoặc bài báo người dùng đưa, rồi viết ra file kịch bản đúng chuẩn. Có hai cách giao bài, tuỳ bản MCP đang cài: - **Bản từ xa** (`https://map.nexusone.vn/mcp`) hoặc không có MCP: giao file `.json`, người dùng mở trên web để xem và tự xuất video. - **Bản cài trên máy** (`npx -y nexus-map-mcp@latest`): agent chụp khung để soát, gửi storyboard, người dùng đồng ý thì xuất MP4 ngay trên máy người dùng. Tài liệu kèm theo: - [references/schema.md](https://map.nexusone.vn/skill/references/schema.md): mọi trường, giá trị hợp lệ, mặc định. - [references/ke-chuyen.md](https://map.nexusone.vn/skill/references/ke-chuyen.md): cách biến một bài tin thành video 30 đến 60 giây. - [references/vi-du.md](https://map.nexusone.vn/skill/references/vi-du.md): khung tối thiểu và các đoạn trích mẫu (caption, tuyến, tiện ích, bay dọc tuyến). - [references/typo.md](https://map.nexusone.vn/skill/references/typo.md): luật tiêu đề chữ khung dọc 9:16 (5 vùng, chọn dòng nhấn, bộ style đã duyệt, tag 3 giây). ### Bốn quy tắc cứng 1. **Không đoán toạ độ thật.** Không tự nghĩ ra `lng`, `lat` hay `points` từ trí nhớ. Mọi vị trí lấy từ công cụ (`find_place`, `get_road`, `find_lot`, `list_library_routes`, `list_library_zones`) hoặc do người dùng đưa. Không tìm được thì hỏi lại, không bịa. 2. **Tuyến quy hoạch, vẽ gần đúng phải đánh dấu.** Đặt `approx: true` (hoặc `kind: "planned"`, tự có approx) và ghi chữ "minh hoạ" trong `hud.disclaimer`, vd "Hướng tuyến minh hoạ theo quy hoạch công bố". Không ghi "vị trí gần đúng" lên hình (`sub`, disclaimer, caption). Vị trí ước thì chỉ báo người dùng trong lời nhắn. 3. **Chữ hiển thị không dùng dấu chấm giữa (U+00B7), gạch dài (U+2014), gạch ngang vừa (U+2013).** Dùng dấu phẩy, dấu chấm hoặc gạch nối thường "-". Tên tuyến trong thư viện có gạch ngang vừa, nên tự viết lại `name`, `label`. 4. **Không tự duyệt storyboard.** Bản cài trên máy: gửi ảnh storyboard cho người dùng và chờ họ đồng ý trong trò chuyện rồi mới `export_video`. Sửa kịch bản sau khi duyệt thì mã duyệt đổi, phải vẽ và duyệt lại. `validate_scene` báo lỗi khi tuyến approx thiếu "minh hoạ", chữ có ký tự cấm hoặc cụm "gần đúng", toạ độ đảo ngược hay nằm ngoài Việt Nam. `export_video` từ chối khi người dùng chưa duyệt storyboard của đúng kịch bản đang xuất. ### Quy trình 1. **Gom dữ kiện.** Từ lời đọc, liệt kê: dự án, địa danh, tuyến đường, con số (km, vốn, năm), mốc thời gian. Thiếu khổ video thì mặc định `9:16`; thiếu độ dài thì ước theo lời đọc (khoảng 2,5 đến 3 chữ mỗi giây với giọng đọc tiếng Việt). 2. **Lấy toạ độ.** - Tuyến: theo bảng "Thứ tự lấy tuyến" bên dưới. - Vùng hành chính (quận, phường, quận cũ như Quận 2): `list_library_zones`, ghi `"preset": ""`, `"points": []`. Không có trong thư viện thì hỏi người dùng, không tự vẽ ranh quận. Khu lịch sử (Sài Gòn, Chợ Lớn) dùng vùng khu `khu-sai-gon`, `khu-cho-lon`, không dùng phường mới cùng tên. - Điểm: `find_place`. Kết quả mơ hồ (nhiều chỗ trùng tên) thì chọn theo quận, tỉnh trong bài; vẫn không chắc thì hỏi. - Điểm dự án, vị trí chính: **xin người dùng gửi toạ độ** nếu họ chưa gửi. Dự án mới, dự án đang bán thường không có hoặc lệch trên OpenStreetMap; đừng lấy `find_place` làm vị trí dự án khi chưa có người dùng xác nhận. Chỉ họ cách lấy: Google Maps trên máy tính: nhấp chuột phải đúng chỗ dự án, dòng đầu là toạ độ (vd 10.7215, 106.7020), bấm vào là chép. Trên điện thoại: nhấn giữ đúng chỗ dự án để thả ghim, toạ độ hiện ở ô tìm kiếm (Android) hoặc trong thẻ kéo lên ở dưới (iPhone), chạm để chép. Google Maps ghi vĩ độ trước (số khoảng 8 đến 23), kinh độ sau (khoảng 102 đến 110): ghi đúng vào `lat`, `lng`. - Tiện ích kề dự án (siêu thị, bệnh viện, trường ngay cạnh) mà kịch bản nhắc: hỏi người order toạ độ kèm hướng dẫn; 3 phút không có phản hồi thì tự đo bằng `find_lot`. Tô lô và gắn tag tiện ích theo `ke-chuyen.md`, mục "Tiện ích kề dự án". - Cũng điểm đó: **hỏi người dùng có ảnh của vị trí không** (ảnh phối cảnh, ảnh thật) để gắn tag ảnh trên ghim (`images[]` với `marker`). Không có thì bỏ qua, không lấy ảnh trên mạng. 3. **Lập bảng phân cảnh** trước khi viết JSON: mỗi dòng là một đoạn lời đọc, giây bắt đầu, góc quay, lớp nào hiện. Đưa người dùng xem nếu kịch bản dài hoặc có chỗ chưa chắc. 4. **Viết JSON** theo [schema](https://map.nexusone.vn/skill/references/schema.md), bắt đầu từ khung tối thiểu trong [vi-du.md](https://map.nexusone.vn/skill/references/vi-du.md). 5. **`validate_scene`.** Sửa hết lỗi (`errors`). Đọc cảnh báo (`warnings`), ghi chú (`notes`) và storyboard trả về; sửa những gì làm video khó xem. Ba loại hay gặp: - Ghim, tag rơi vào vùng 1 hoặc 5 của khung dọc (lỗi), vùng 2 hoặc 4 (cảnh báo): sửa bằng camera (dời tâm, lùi zoom), không dời chữ, không ẩn tag. - `nhãn: ... bị ẩn ... khi xuất tuần tự`: tag, tên vùng sẽ mất trong video dù xem trước vẫn thấy. Cụm điểm gần nhau cho chung `group`; vòng dồn lại khi máy lùi xa thì ghi `shortName` (xem schema, vùng). - Máy quay giữ khung mà cụm nội dung lệch tâm hoặc lùi quá xa: lấy `lng`, `lat`, `zoom` gợi ý trong cảnh báo. 6. **Giao bài.** - Bản từ xa hoặc không có MCP: ghi file `.json`, đưa người dùng mở trên web (mục "Mở kịch bản trên web"). - Bản cài trên máy, làm trọn theo thứ tự: 1. `save_scene` ra file `.json`. 2. Bay dọc tuyến có câu `say`: `make_voice` (với `path`) trước khi chụp khung. Báo thiếu khoá thì chỉ người dùng trang https://map.nexusone.vn/mcp mục Giọng đọc, hoặc xuất không tiếng. 3. `preview_frames`, tự soát chữ đè, tuyến lệch, góc máy; sửa tới khi khung hình ổn. 4. `storyboard`, gửi ảnh cho người dùng và **chờ người dùng đồng ý** (quy tắc 4). 5. `export_video` theo `approval` trong kết quả `storyboard`: `hop-hoi` thì gọi khi người dùng muốn xuất, ứng dụng hiện hộp hỏi để chính họ bấm đồng ý; `trang` thì đưa người dùng link `approval_page` (trang duyệt trên máy), họ bấm "Đồng ý xuất" rồi mới gọi; `chat` (máy không người ngồi, hoặc gói cũ không có trường `approval`) thì gọi với `review_code` và `user_approval` (lời đồng ý chép nguyên văn). Kết quả `state: "needs_approval"` là người dùng chưa đồng ý: đọc `user_feedback`, sửa rồi vẽ storyboard lại, không gọi lại ngay. 6. `export_status` (`wait_seconds: 50`) tới khi `state` là `done`, rồi báo đường dẫn file MP4. 7. **Báo người dùng** đường dẫn file, cách mở, và những điểm cần tự kiểm tra (vị trí ước, tuyến minh hoạ, câu chữ). Chỉ báo trong lời nhắn, không ghi "vị trí gần đúng" lên hình. ### Thứ tự lấy tuyến | Bước | Công cụ | Khi nào | Ghi vào kịch bản | |---|---|---|---| | 1 | `list_library_routes` | metro, vành đai, cao tốc lớn ở TP.HCM, Hà Nội; nhắc tới vành đai thì luôn dùng preset để chạy hết tuyến | `"preset": ""`, `"points": []` | | 2 | `get_road` | đường có tên trên bản đồ | dán nguyên khối `route` trả về | | 3 | `get_road` + `from`, `to` | đoạn đường giữa hai điểm, đường chưa có tên | `route` trả về (đường đi xe thực tế, đã làm thẳng: chỉ cong ở chỗ rẽ, bỏ vòng quay đầu) | | 4 | hỏi người dùng | tuyến chỉ có trên giấy, không có dữ liệu | | `get_road` báo `warning` khi tuyến còn là quy hoạch hoặc đang thi công: khi đó đặt `approx: true` hoặc `kind` tương ứng, và thêm "minh hoạ" vào disclaimer. Điểm `from` hoặc `to` nằm ngoài đường (khu đất chưa có lối ra trên bản đồ): `get_road` tự bỏ đoạn vòng qua đường nhánh, nối thẳng từ điểm ra trục gần nhất và báo `warning`. Khi đó hỏi người dùng lối ra thật (nhìn trên Google Maps cũng được), rồi gọi lại với `via` là một điểm trên lối ra đó. `validate_scene` cảnh báo tuyến OSRM còn vòng quanh điểm đầu hoặc cuối. ### Kịch bản về tuyến metro, ga metro: dùng `tour` Lời đọc đi qua từng ga của một tuyến metro (giới thiệu tuyến, ga, TOD quanh ga), hoặc tập trung vào một ga metro: **không tự viết keyframe dọc tuyến**. Ghi trường `tour` ([schema](https://map.nexusone.vn/skill/references/schema.md), mục tour), đúng thứ nút "Bay dọc tuyến" của web ghi ra, nên video ra y hệt người dùng tự bấm nút. 1. `list_library_routes` (query "metro"): lấy `id` và danh sách `stations` của tuyến. Ghi tuyến vào `routes[]` bằng `preset`. 2. `"tour": { "route": "", "from": "", "to": "" }`. Một ga: `from` = `to` = ga đó, `dwell` 8 đến 12. 3. Thông tin từng ga lấy từ lời đọc: `tour.stations` (`note`, `tags`, `transfer`). Nút TOD quanh ga: vùng tròn `glow: true`, `area` (ha) theo số công bố. 4. Lời đọc: ghi câu đọc của từng ga vào `tour.stations[].say`, câu mở đầu vào `tour.say` (ngắn, dưới 35 chữ mỗi câu). Web tự giãn giây dừng ga theo câu, hiện câu làm phụ đề và phát file tiếng đúng lúc dừng ga; không cần `captions[]` cho các câu này. 5. `validate_scene`: đặt `duration` theo giây kết thúc chuyến bay (storyboard có mốc "dừng ga N" và từng câu đọc). Bản trên máy: `make_voice` đọc mọi câu `say` thành tiếng, tự khớp giây và nới `duration`. ### Nhịp và độ dễ đọc Góc máy và lớp: - Nghiêng máy (`pitch`) tối đa 30 độ. Keyframe camera cách nhau 2 đến 3 giây; tốc độ zoom không quá 0,8 bậc mỗi giây (nhanh hơn thì chóng mặt). - Các lớp xuất hiện lệch nhau 1,5 đến 2 giây, không bật cùng lúc. Cùng một lúc không quá 8 lớp trên bản đồ (tuyến, vùng, điểm, chữ). - Tuyến ghi `"flow": true, "dash": true` (nét đứt chạy, kiểu mặc định của web). - Tên đường (`label` của tuyến đường thường) web viết dọc theo nét; `labelSize` từ 32 trở lên. Tag (khung màu, một cỡ chung) chỉ dành cho dự án, metro, quy hoạch, tiện ích. - Chú giải tối đa 6 dòng. Màu: - Video BĐS ghi `"basemap": "satellite-soft"` và `"theme": "ba-vai"` (mục Bảng màu trong `references/schema.md`). Web tự tô ghim và khu dự án màu cam, tuyến vàng, vùng xung quanh xanh dương, điểm khác màu lạnh, tuyến nói xong lùi xám, thẻ trắng chữ đen. - Người dùng muốn bản đồ đêm, đường vàng phát sáng thì ghi `"basemap": "satellite-night"` và `"theme": "vang-dem"`. - Không tự đặt `color` từng mục, trừ khi người dùng muốn màu riêng (`"vai": "rieng"`). Chữ: - Mỗi caption một dòng nhấn `hook`: in hoa, nên trong khoảng 12 ký tự (quá 20 thì `validate_scene` cảnh báo); `lead` dẫn và `extra` bổ sung viết thường. Cách chọn dòng nhấn: [typo.md](https://map.nexusone.vn/skill/references/typo.md). - Câu có `hook` thì web không hiện `sub`; 3 giây đầu clip cũng không hiện phụ đề. Ý cần người xem đọc được ở câu đó phải nằm trong `lead`, `hook`, `extra`. - Không ghi `titleStyle`, `titleColor`: web tự bốc style và họ màu theo kịch bản. Chỉ ghi khi người dùng chọn. - `sub` tối đa khoảng 100 ký tự, caption không chồng thời gian. - Video dọc 9:16: tiêu đề ở vùng 2 (8% đến 30% chiều cao), ghim, tag, tuyến chính ở vùng 3 (30% đến 79%), tránh mép trên, mép dưới (nơi nút của Reels, TikTok che). - Chip ghi chú suốt video (`hud.note`, vd "Hướng tuyến dự kiến") và tên kênh cuối video (`outro.name`, chữ nhỏ góc dưới phải) khi người dùng có kênh: [schema](https://map.nexusone.vn/skill/references/schema.md), mục outro. - Liên hệ: Zalo, địa chỉ web, mã QR không gắn lên video ở khổ nào. Số điện thoại chỉ ghi ở bản ngang 16:9. Khổ dọc dùng câu kêu gọi trong ứng dụng (vd "Nhắn tin để được tư vấn"), không dùng `hud.author`. - Không tự điền tên công ty, tên sàn, tên tài khoản lên hình khi người dùng không đưa; tên dự án chỉ ở một tag (ghim dự án). ### Âm thanh - Kịch bản không ghi gì về âm thanh thì video vẫn có tiếng: web tự thêm nhạc nền mặc định và tiếng hiệu ứng theo chuyển động (tiêu đề, tuyến, vùng, ghim). Không cần viết `audio[]` cho các tiếng này. - Người dùng dặn không nhạc thì ghi `"music": false` ở gốc kịch bản; không tiếng hiệu ứng thì `"sfxAuto": false`. Không tự thêm nhạc, tiếng khác khi người dùng không yêu cầu. - Lời đọc: file tiếng người dùng đưa ghi vào `audio[]` (`kind: "voice"`); bay dọc tuyến thì `make_voice` đọc các câu `say`. Chi tiết ở [schema](https://map.nexusone.vn/skill/references/schema.md), mục audio. ### Công cụ MCP Cài một lần theo trang https://map.nexusone.vn/mcp (có lệnh cho từng ứng dụng), agent sẽ có: | Công cụ | Việc | |---|---| | `get_guide` | đọc tài liệu này và các phần tham chiếu | | `find_place` | tìm toạ độ địa điểm ở Việt Nam (OpenStreetMap) | | `get_road` | lấy hình dạng tuyến theo tên, hoặc đường đi giữa hai điểm | | `find_lot` | ranh lô thật của tiện ích quanh dự án (bệnh viện, trường, siêu thị, chợ, công viên), trả `zone` dán vào `zones[]` | | `list_library_routes` | danh sách tuyến có sẵn (metro, vành đai, cao tốc) ở TP.HCM, Hà Nội | | `list_library_zones` | danh sách vùng có sẵn: ranh giới hành chính thật, kể cả quận cũ đã giải thể | | `validate_scene` | kiểm tra kịch bản, trả lỗi, cảnh báo, ghi chú, storyboard theo giây | | `save_scene` | ghi file `.json` (từ chối khi còn lỗi, trừ khi `force`) | | `preview_frames` | chụp vài khung hình JPEG render y như video xuất, để tự soát chữ đè, tuyến lệch, góc máy | | `storyboard` | tờ duyệt trước khi xuất: mỗi ô một đoạn đường máy quay, khung thật đầu và cuối đoạn (typo thật), giây, hướng bay, chữ hiện ra; trả ảnh và cách duyệt `approval` (`hop-hoi`, `trang` kèm `approval_page`, `chat` kèm `review_code`) | | `export_video` | xuất MP4 trên máy người dùng (chạy nền, trả `job_id`); chỉ chạy khi chính người dùng đã duyệt storyboard (hộp hỏi, trang duyệt; cách `chat` cần `review_code` và `user_approval`), chưa duyệt thì trả `needs_approval` | | `export_status` | tiến độ, đường dẫn file khi xong, huỷ | | `make_voice` | đọc câu `say` của bay dọc tuyến thành file tiếng (Google, khoá `GOOGLE_TTS_KEY` của người dùng), khớp giây với lúc dừng ga | Bảy công cụ đầu có ở cả hai bản. Sáu công cụ cuối chỉ có ở bản cài trên máy (`npx -y nexus-map-mcp@latest` hoặc chạy từ repo); có thì làm trọn theo bước 6 của Quy trình, không có thì đưa file `.json` để người dùng mở trên web. Không có MCP thì vẫn viết được kịch bản theo tài liệu này, nhưng phải xin người dùng toạ độ (quy tắc 1). ### Mở kịch bản trên web - Vào https://map.nexusone.vn, bấm **Mở dự án**, chọn file `.json`. - Hoặc mở tab **JSON**, dán nội dung, bấm **Áp dụng JSON**. - Kịch bản đã đưa lên mạng: `https://map.nexusone.vn/?kich-ban=<đường dẫn file>`. Web tự nạp tuyến `preset` và tuyến `osm` chưa có điểm khi mở file, nên lần mở đầu có thể chờ vài giây. ## Schema v1: kịch bản video bản đồ Một kịch bản là một file JSON. Web (map.nexusone.vn) đọc file qua bộ chuẩn hoá `normalizeScript`: trường thiếu thì điền mặc định, giá trị lạ thì **lặng lẽ** đổi về mặc định. Vì vậy viết đúng tên, đúng giá trị liệt kê dưới đây, rồi gọi `validate_scene` để chắc web hiểu đúng ý. Quy ước chung: - Toạ độ luôn là `[lng, lat]` (kinh độ trước). Việt Nam nằm trong khoảng lng 102 đến 110, lat 8 đến 24. - Thời gian tính bằng giây từ đầu video. Mọi lớp hiện trên video có `start`, `end` (thiếu `start` là 0, thiếu `end` là hết video). - Cỡ chữ, độ dày nét, cỡ điểm tính bằng px trên khung có cạnh ngắn 1080 px (khổ nào cũng vậy). - Màu viết dạng `#rrggbb`. Viết sai dạng thì web dùng màu mặc định. - Trường không có trong bảng thì web giữ nguyên nhưng không dùng. ### Khung ngoài | Trường | Kiểu | Mặc định | Ghi chú | |---|---|---|---| | `version` | số | 1 | luôn ghi `1` | | `format` | chuỗi | `"16:9"` | `"9:16"` (Reels, TikTok), `"16:9"`, `"1:1"` | | `duration` | số | 10 | độ dài video, giây | | `basemap` | chuỗi | `"satellite-soft"` | xem bảng nền bản đồ | | `look` | object | `{}` | chỉnh màu toàn khung | | `theme` | chuỗi | | `"ba-vai"`: bảng màu 3 vai, thẻ trắng; `"vang-dem"`: vàng đêm, đường vàng phát sáng (xem mục Bảng màu). Bỏ trống là màu theo từng mục | | `routeAutoColor`, `routeSkipMain` | bool | true | `false` để tắt màu tự động cho tuyến phụ, tắt bỏ qua màu trùng tuyến chính | | `hud` | object | `{}` | nhãn đầu video, chú thích nguồn, la bàn | | `camera` | mảng | | keyframe góc quay, bắt buộc có | | `routes` | mảng | | tuyến đường, metro, cao tốc | | `zones` | mảng | | vùng tròn hoặc đa giác | | `markers` | mảng | | điểm, ga, sân bay, thẻ thông tin, tàu chạy | | `captions` | mảng | | phụ đề theo lời đọc | | `legends` | mảng | | khung chú giải | | `texts` | mảng | | chữ phủ tự do | | `ctas` | mảng | | khung kêu gọi cuối video | | `scenes` | mảng | | chia cảnh (tuỳ chọn) | | `images` | mảng | | ảnh phủ, ảnh gắn vào điểm (xem `images[]` dưới); chỉ thêm khi người dùng có ảnh | | `tagSize` | số hoặc object | 1 | cỡ tag và chữ trong tag, hệ số 0,5 đến 2 (1 là cỡ thường, 1.3 là to hơn 30 %). Một số là mọi tag; object theo loại: `place` (tag ghim, điểm), `road` (tên đường viết dọc nét và tag tuyến đường: quy hoạch, đường tới tiện ích), `amenity` (tag tiện ích, `card` có `target`), `metro` (tag tuyến metro, đường sắt), `zone` (tên vùng), vd `{"place": 1.2, "metro": 1.4}`. Từng điểm, tuyến, vùng ghi `tagSize` số thì thay hệ số của loại cho riêng mục đó. Chỉ ghi khi người dùng muốn tag to, nhỏ hơn; tag to thì dễ chạm nhau hơn, `validate_scene` tính theo cỡ mới | | `vienPhuDe` | màu | `#15803d` | màu viền chữ phụ đề `sub` cả clip (mặc định xanh lá); caption ghi `vienPhuDe` riêng thì theo caption. Gợi ý: lấy màu chữ, màu thương hiệu nổi bật của dự án; không dùng viền đen | ### Nền bản đồ (`basemap`) `satellite-vivid` (vệ tinh tươi), `satellite` (vệ tinh), `satellite-soft` (vệ tinh dịu: bớt rực, hơi tối, tuyến và ghim nổi lên), `satellite-dark` (vệ tinh tối, đường nổi), `satellite-night` (vệ tinh đêm vàng: ảnh vệ tinh tối ánh xanh rêu, chỉ trục chính sáng vàng có quầng; đi cùng `theme: "vang-dem"`), `dark` (tối tối giản), `dark-gold` (đêm đường vàng), `blueprint` (xanh kỹ thuật), `light` (sáng tối giản), `streets` (đường phố), `bright` (đường phố sáng), `positron` (xám nhạt), `topo` (địa hình), `natgeo` (National Geographic, chỉ rõ tới zoom 12). Video BĐS mặc định dùng `"basemap": "satellite-soft"` cùng `"theme": "ba-vai"` (Phương chọn 07/11/2026; từ 10/11/2026 web tạo dự án mới cũng vậy, kịch bản bỏ trống `basemap` thì ra `satellite-soft`). `satellite-vivid` (sáng, rực, hơi ấm) chỉ dùng khi người dùng muốn nền tươi; chỉ thêm `look` làm tối khi người dùng muốn nền tối hơn nữa. Dòng ghi nguồn góc khung tự theo nền: nền vệ tinh ghi "Ảnh vệ tinh © Esri, Maxar", nền vẽ của Esri (tối, sáng, đường phố, địa hình) ghi "Bản đồ nền © Esri", kèm "Dữ liệu © OpenStreetMap". `hud.source` ghi thì thay cả dòng. ### Bảng màu (`theme: "ba-vai"`) Nền trung tính, ghim dự án màu ấm, tuyến vàng, vùng xung quanh xanh dương, thứ đang nói màu lạnh, tuyến nói xong lùi xám: | Vai | Vệ tinh | Nền tối | Nền sáng | Mặc định áp cho | |---|---|---|---|---| | `am` (ấm) | `#f3a86b` | `#f3a86b` | `#e0782f` | ghim dự án (`kind: "pin"`), vùng khu dự án (vùng chứa ghim dự án, không có thẻ `card` trỏ tới, trừ vùng `autoColor`), dòng phụ chú giải | | tuyến (mặc định, không phải vai) | `#ffc83d` | `#ffc83d` | `#ca8a04` | tuyến không ghi `vai` (vàng; nét đứt theo `flow` + `dash` như mọi tuyến) | | vùng xung quanh (mặc định, không phải vai) | `#38bdf8` | `#38bdf8` | `#0284c7` | vùng không chứa ghim dự án, không có thẻ `card` trỏ tới (vd Phú Mỹ Hưng cạnh dự án) | | `lanh` (lạnh) | `#2fd4f0` | `#2fd4f0` | `#0891b2` | điểm khác ghim, lô tiện ích (vùng có thẻ `card` trỏ tới), dòng chú giải không trùng tên tuyến, vùng nào (trùng thì lấy màu mục đó); tuyến, vùng ghi `"vai": "lanh"` | | `xam` (xám) | `#a3adbb` | `#6b7686` | `#9aa3af` | tuyến đã nói xong | - Web tự đặt `color` theo vai, nên không cần ghi màu. Mục nào cần vai khác thì ghi `"vai": "am"`, `"lanh"`, `"xam"`; `"vai": "rieng"` giữ màu tự đặt. Dòng `legends[].rows[]` cũng nhận `vai`. - Tuyến có `end` sớm hơn hết video 0,3 s trở lên thì web tự sinh tuyến xám mảnh (`id` thêm `-xam`, `auto: "xam"`, nét tĩnh, không tên, không vào chú giải), hiện từ 1,1 s trước lúc tuyến chính tắt tới hết video: khách vẫn thấy tuyến vừa nói nhưng mắt dồn sang thứ đang nói. Không tự viết tuyến này; muốn tuyến chính ở tới hết video thì để `end` trống. Tuyến `"vai": "xam"` thì xám, tĩnh ngay từ đầu. - Tag, la bàn, khung chú giải thành thẻ trắng chữ đen. Chữ tiêu đề (Typo) không đổi. ### Bảng màu vàng đêm (`theme: "vang-dem"`) Kiểu bản đồ đêm sang: ghi `"basemap": "satellite-night"` cùng `"theme": "vang-dem"` khi người dùng muốn nền tối, đường vàng phát sáng, khu dự án sáng vàng (web chọn ô Bảng màu "Vàng đêm" là tự đổi nền). - Cả clip một họ vàng: `am` `#f5c04a` (ghim, vùng), `lanh` `#ffe6a6` (tuyến, điểm khác, lô tiện ích), `xam` `#8a7a55` (tuyến nói xong). `vai` từng mục, tuyến xám tự sinh như `ba-vai`. - Mọi vùng (trừ `"vai": "rieng"`) tự có `glow: true` (vùng `spotlight` giữ kiểu của nó), `glowK: 2.5` (quầng toả rộng như ảnh mẫu), `streets: true` (đường xe chạy nằm trọn trong vùng sáng vàng như mạng đèn đêm), bỏ `casing`, `fillOpacity` tối đa 0,16, `width` tối đa 5. - Tag ghim dự án và tên vùng là thẻ kính tối viền vàng, chữ có chân Playfair Display, tên vùng giữ hoa thường như kịch bản. Tag điểm khác, tag tuyến là chữ trơn sáng có bóng, không khung. Chú giải, la bàn nền tối viền vàng. Chữ tiêu đề (Typo) không đổi. ### `look` | Trường | Khoảng | Ghi chú | |---|---|---| | `brightness` | -1 đến 1 | âm là tối hơn | | `saturation` | -1 đến 1 | âm là nhạt màu | | `tint` | màu | phủ một lớp màu | | `tintStrength` | 0 đến 1 | độ đậm lớp phủ | | `vignette` | 0 đến 1 | tối viền khung | | `warmth` | 0 đến 1 | ngả ấm (nâu vàng nhẹ) | | `shade` | 0 đến 0,2 | "Phủ tối": phủ xanh đen `#0b1220` đúng mức này kèm viền tối gấp 6 lần, tối đa 0,9 (0,1 thì viền 0,6). Thanh trên web chỉnh 0,1 đến 0,2. Thiếu thì 0, dự án mới tạo trên web đặt 0,1 | | `edge` | false | "Tối mép trên, dưới": đen phủ thêm 7% sát mép trên và mép dưới, 5% ở 10% chiều cao, nhạt hết ở 25% (đọc rõ tiêu đề, phụ đề). Dự án mới tạo trên web bật sẵn | Ví dụ khi cần nền tối: `{"brightness":-0.3,"saturation":-0.15,"tint":"#0b1220","tintStrength":0.22,"vignette":0.9}`. ### `hud` | Trường | Ghi chú | |---|---| | `badge`, `badgeColor` | nhãn nhỏ góc trên, vd "HẠ TẦNG PHÍA NAM" | | `title` | tiêu đề lớn đầu video | | `headEnd` | giây tắt badge và title (0 là hiện suốt) | | `tag`, `tagColor` | nhãn nhỏ trên phụ đề, dùng chung cho mọi caption không có `tag` riêng | | `author`, `authorTag` | tên kênh, người làm, hiện suốt video ở góc dưới trái. Chỉ ghi khi người dùng đưa tên và muốn hiện; không tự điền tên công ty, tên tài khoản. Khổ 9:16 không dùng (TikTok che góc đó), tên kênh để `outro.name` | | `compass` | la bàn, mặc định bật; `false` để tắt | | `disclaimer` | ghi chú nguồn, mức minh hoạ; không hiện trên video (dòng nguồn `source` vẫn hiện); **bắt buộc có chữ "minh hoạ" khi có tuyến `approx`** | | `disclaimerFrom` | giây bắt đầu hiện disclaimer | | `source` | nguồn tin | | `note`, `noteColor` | chip ghi chú nhỏ ở đáy khung, hiện suốt video, vd "Hướng tuyến dự kiến", "Phối cảnh minh hoạ"; dưới 40 ký tự; `noteColor` mặc định `#f59e0b`. Có `author` thì chip đứng trên dòng tác giả | Badge và title tự ẩn khi đang có chú giải hoặc CTA trên màn hình. ### `outro`: tên kênh cuối video (tuỳ chọn) Một object ở gốc kịch bản. Mấy giây cuối video hiện tên kênh bằng chữ nhỏ ở góc dưới phải khung, ngay trên dòng nguồn bản đồ: chữ vàng kim, quét hiện từ trái sang, rồi một vệt sáng lướt qua. Chỉ một dòng chữ: không logo, handle, liên hệ, hộp nguồn. Chip `hud.note` vẫn hiện. Tag trên bản đồ tự né chữ này. | Trường | Ghi chú | |---|---| | `name` | tên kênh, thương hiệu của người dùng; không có thì lấy `hud.author`. Thiếu cả hai thì không hiện | | `color` | màu chữ `#rrggbb`; không ghi thì chữ vàng kim có vệt sáng, ghi thì chữ một màu, không vệt sáng | | `dur` | số giây cuối video, 1 đến 15, mặc định 4 | Không ghi Zalo, địa chỉ web, mã QR trong `name` ở khổ nào; số điện thoại chỉ ở bản ngang 16:9 (quy tắc 4 cuối file): `validate_scene` cảnh báo. Không có `outro` (hoặc thiếu cả `name` lẫn `hud.author`) thì cuối clip không ký tên gì. ```json "outro": { "name": "Kênh Nhà Đất Sài Gòn" } ``` ### `camera[]`: keyframe góc quay | Trường | Ghi chú | |---|---| | `t` | giây; keyframe không có `t` bị bỏ | | `lng`, `lat` | tâm khung; keyframe đầu tiên bắt buộc có, các keyframe sau thiếu thì lấy theo keyframe trước | | `zoom` | mặc định 12; toàn thành phố khoảng 10 đến 11, một quận 13, một dự án 15 đến 16 | | `pitch` | độ nghiêng 0 đến 85; **nên tối đa 30** (máy thấp hơn thì đường, nhãn ở xa bị nén, khó đọc; `validate_scene` cảnh báo khi quá 30) | | `bearing` | hướng xoay, độ | | `ease` | `inOut` (mặc định), `linear`, `in`, `out`, `fastSlow`, `slowFast`, `outIn` | | `views` | tuỳ chọn: góc riêng cho từng khổ, vd `{"16:9":{"lng":..,"lat":..,"zoom":..}}` | Web sắp keyframe theo `t` rồi nội suy giữa hai keyframe kề nhau. **5 vùng của khung dọc 9:16** (từ trên xuống): vùng 1 là 0 đến 8% chiều cao (cấm, chỗ giao diện app); vùng 2 là 8% đến 30% (khối tiêu đề); vùng 3 là 30% đến 79% (bản đồ); vùng 4 là 79% đến 87,5% (phụ đề); vùng 5 là 87,5% đến đáy (cấm). Ghim, tag dự án và điểm đến đang hiện phải nằm trong vùng 3 ở **mọi khung**, kể cả lúc máy quay đang bay giữa hai keyframe. Đặt tâm keyframe sao cho điểm chính ở khoảng giữa vùng 3 (hơi thấp hơn tâm khung), và kiểm cả đoạn giữa hai keyframe. `validate_scene` báo lỗi khi một ghim rơi vào vùng 1 hoặc 5 từ 0,25 giây trở lên, báo cảnh báo khi vào vùng 2 hoặc 4. Cách sửa: dời tâm, lùi zoom, thêm keyframe ở đoạn bị lệch, hoặc cho điểm tắt (`end`) khi cảnh của nó đã hết. Trên web, nút **Đưa ghim, tag vào vùng 3** trong bảng Camera tự làm việc này. Ghim dự án (`kind: pin`) còn phải cách mép trái, mép phải từ 6% bề ngang: nằm sát mép từ 0,5 giây trở lên thì `validate_scene` cảnh báo "sát mép trái" hoặc "sát mép phải". Zoom giữa hai keyframe liền nhau nên giữ dưới 0,8 mức mỗi giây (nhanh hơn là giật); nút trên web giữ tốc độ này cho keyframe nó chỉnh hoặc thêm. ### `routes[]`: tuyến | Trường | Mặc định | Ghi chú | |---|---|---| | `id` | `duong-N` | duy nhất, để `of`, tàu, chú giải trỏ tới | | `name` | | tên hiện trong chú giải tự sinh | | `label` | | chữ hiện **trên bản đồ** (không có thì không hiện). Đường thường: tên viết nằm ngay trên nét, uốn theo tuyến, chữ trắng viền tối, giữ hoa thường như đã gõ, nhỏ lại khi zoom ra. Metro, đường sắt, tuyến quy hoạch (`planned`, `other-planned`, `approx`) và đường đi tới tiện ích: hiện thành tag (khung màu) cỡ cố định | | `points` | `[]` | mảng `[lng, lat]`, ít nhất 2 điểm, trừ khi dùng `preset`, `osm` hoặc `of` | | `preset` | | id tuyến có sẵn (xem `list_library_routes`); để `points: []`, web tự nạp hình dạng. Vành đai TP.HCM: `vanh-dai-2`, `vanh-dai-3` khép kín cả vòng, `vanh-dai-4-hcm` tới Hiệp Phước, `vanh-dai-1` là cung từ Linh Đông tới Nguyễn Văn Linh (hai đầu trên Vành đai 2, có khúc quy hoạch gần đúng): nhắc tới vành đai thì dùng preset để chạy hết tuyến | | `osm`, `osmResolved`, `osmDate`, `osmSource` | | do `get_road` điền; có đủ thì web không tải lại | | `stations` | | tuyến metro: mảng `{name, lng, lat}` các ga; web chấm tròn từng ga (đĩa trắng, lõi màu tuyến) khi nét vẽ tới. Tuyến có sẵn `metro-…` mang sẵn ga, không cần ghi. Đoạn tô (`of`) dùng ga của tuyến cha. Tool gốc bỏ qua | | `stationsOff` | false | `true` là tắt chấm ga (ô "Chấm ga metro" bỏ tích) | | `kind` | | trạng thái, điền sẵn màu, nét, hiệu ứng (bảng dưới) | | `infra` | | loại hạ tầng, điền sẵn màu (bảng dưới) | | `color` | `#ffc83d` | ghi đè màu của `kind`, `infra` | | `width` | 12 | độ dày nét | | `effect` | `draw-pulse` | `draw-pulse`, `draw`, `pulse`, `breathe`, `static`, `arrows`, `dash-flow`, `dots` | | `flow` | false | `true` là kiểu "Đầu sáng và dải luân phiên" (tuyến mới tạo trên web mặc định bật, kèm `dash: true`); `effect` vẫn lưu `draw-pulse` để tool gốc đọc được. **Mỗi tuyến nên ghi `"flow": true, "dash": true`** (nét đứt chạy, kiểu đẹp nhất), trừ khi người dùng muốn kiểu khác | | `speed` | 1 | chỉ khi `flow`: tốc độ chạy, 0 đến 2 | | `neon` | `core-breathe` | chỉ khi `flow`: `core-breathe` (lõi giữa khúc + ống thở chậm), `none`, `tube` (ống liền), `core` (lõi giữa khúc), `wrap` (bọc từng khúc), `breathe` (thở chậm) | | `neonLevel` | 1 | chỉ khi `flow`: độ sáng neon, 0 đến 2 | | `segLen` | `medium` | chỉ khi `flow`: độ dài khúc `short`, `medium`, `long` | | `casing`, `smooth` | true | chỉ khi `flow`: `false` để bỏ viền tối quanh khúc, bỏ bo góc tuyến | | `drawTime` | 3 | giây vẽ xong tuyến kể từ `start` | | `dash` | false | nét đứt | | `approx` | false | hình dạng gần đúng (tuyến quy hoạch, vẽ tay) | | `labelSize` | 40 | cỡ chữ tên đường viết dọc tuyến (tag không theo trường này; cỡ tag chỉnh bằng `tagSize`) | | `tagSize` | | hệ số cỡ riêng tuyến này, 0,5 đến 2: thay `tagSize.road` (hoặc `tagSize.metro` với tuyến metro) của kịch bản, áp cả tên đường dọc nét lẫn tag | | (luật đặt nhãn) | | tag và tên đường luôn cách nhau ít nhất 50% chiều dài của nhãn dài hơn; tên đường tự chọn đoạn tuyến nằm ngang nhất (dễ đọc), `labelPos` chỉ là gợi ý; tag dự án được ưu tiên giữ chỗ, hết chỗ thì tên đường ẩn; **mỗi tag đã hiện thì đứng yên ít nhất 3 s liên tục** (khách kịp đọc): tag đang trong 3 s đầu chỉ cần không đè, tag sắp hết hạn hay sắp hết video mà chưa kịp hiện thì bỏ hẳn, không hiện chớp (riêng tag sống dưới 6 s chưa hiện lần nào thì còn nửa đời là được hiện, tới hết hạn); tag thời gian của tuyến và tag điểm đến của chính tuyến đó ("15 đến 20 phút" với "Quận 1") là một cặp, đứng sát nhau được; `validate_scene` cảnh báo tag sống dưới 5 s (chờ chỗ rồi vẫn đủ 3 s) và tên ghim quá 6 chữ (tên ghim chỉ để tên dự án, chi tiết đưa vào caption); `validate_scene` còn chạy thử bộ né nhãn theo từng 0,1 giây như lúc xuất và báo tag, tên vùng nào bị ẩn từ 0,3 giây trở lên ("bị ẩn từ ... khi xuất tuần tự, không còn chỗ cạnh ..."): xem trước tua nhảy xếp lại từ đầu nên có thể vẫn thấy, video xuất thì không. Sửa bằng `group` chung, `shortName` cho tên vùng khi lùi xa, hoặc dời `start` | | `labelFont` | `bold` | `bold`, `regular`, `italic` | | `labelUpper` | true | viết hoa chữ trong tag; tên đường viết dọc tuyến giữ nguyên như đã gõ | | `labelPos` | 0.5 | vị trí nhãn dọc tuyến, 0 đến 1 | | `of`, `from`, `to` | | đoạn của tuyến khác: `of` là id tuyến cha, `from`, `to` là phần 0 đến 1 dọc tuyến cha | | `legend`, `legendLabel` | | `legend: false` để bỏ khỏi chú giải tự sinh; `legendLabel` thay tên trong chú giải | | `start`, `end` | 0, hết video | | Trạng thái (`kind`): | kind | Nghĩa | Màu | Hiệu ứng | Nét | |---|---|---|---|---| | `new` | tuyến chính của tin | #f97316 | draw-pulse | liền | | `existing` | đang khai thác | #ef4444 | pulse | liền | | `construction` | đang thi công | #f59e0b | draw | liền, vạch chéo | | `planned` | quy hoạch (tự đặt `approx: true`) | #fb923c | breathe | đứt | | `other-planned` | dự án khác, quy hoạch | #a855f7 | breathe | đứt | | `highlight` | đoạn cần nhấn | #fde047 | draw | liền | | `road-label` | chỉ để ghi tên đường | #ffffff | static, dày 4 | liền | Loại hạ tầng (`infra`): `metro` #f43f5e, `rail` #c084fc, `expressway` #22c55e, `ring` (vành đai) #38bdf8, `highway` (quốc lộ) #facc15, `provincial` (tỉnh lộ) #fb923c, `urban` (đường đô thị) #f8fafc, `bridge` #2dd4bf. ### `zones[]`: vùng | Trường | Mặc định | Ghi chú | |---|---|---| | `id`, `name` | | `name` hiện khi `showLabel: true` | | `kind` | tự đoán | `circle` (cần `center` + `radius` mét, mặc định 300) hoặc `polygon` (cần `points`, ít nhất 3 điểm, hoặc `preset`) | | `preset` | | id vùng có sẵn (xem `list_library_zones`): ranh giới hành chính thật, kể cả quận cũ đã giải thể; để `points: []`, web tự nạp ranh giới khi mở file. Tên lịch sử trùng tên phường mới thì đọc `note`: lời đọc nói khu, lõi Sài Gòn, Chợ Lớn dùng `khu-sai-gon`, `khu-cho-lon` (theo ranh Quận 1, Quận 5 cũ; `khu-cho-lon-rong` gộp thêm Quận 6, 11 cũ), không dùng `phuong-sai-gon`, `phuong-cho-lon` (phường mới từ 07/2025, chỉ vài km²) | | `color` | #38bdf8 | `"auto"` = máy chọn màu, khác màu mọi vùng kề (như `autoColor: "neighbor"`) | | `autoColor` | | máy tự tô màu, màu tính ra ghi vào `color`: `neighbor` = hai vùng sát nhau (chung ranh từ 50 m) hoặc chồng nhau không trùng màu, ưu tiên màu chưa vùng nào dùng; màu theo `id` nên mở lại vẫn như cũ, vùng thêm sau không đổi màu vùng trước. `type` = theo loại: phường xanh dương, xã xanh lá, đặc khu tím, quận huyện cũ cam, tỉnh thành đỏ hồng, khu vực ngọc. `area` = theo diện tích: dưới 2 km² vàng nhạt, 2 đến 10 cam nhạt, 10 đến 50 hồng, 50 đến 200 hồng tím, từ 200 tím. Dùng khi hiện nhiều phường, quận cùng lúc; vùng ghi `color` tay (không `autoColor`) giữ màu và vùng tự động né màu đó | | `fillOpacity` | 0.35 | 0 đến 1; vùng hành chính, khu dự án nên 0.3 đến 0.4 (dưới 0.25 khó thấy trên nền tối); vòng bán kính để nhạt khoảng 0.08 | | `width` | 8 | độ dày viền | | `dash` | false | viền nét đứt | | `dashMove` | false | khi `dash: true`: nét đứt chạy chậm quanh viền theo chiều kim đồng hồ (Kiểu viền "Đứt chạy") | | `casing` | false | viền lót trắng: nét trắng rộng hơn nằm dưới viền màu, ranh rõ trên cả nền tối lẫn nền sáng, nhiều vùng sát nhau tách bạch. Vùng tạo trên web bật sẵn; viết kịch bản thì ghi `casing: true` cho mọi vùng, trừ vòng bán kính nét đứt. Bỏ qua khi `spotlight` | | `showLabel` | false | | | `labelStyle` | `standing` | `standing` (đứng) hoặc `ground` (nằm trên mặt đất) | | `labelSize` | 40 | không còn tác dụng: tên vùng là tag, cỡ theo `tagSize.zone` của kịch bản | | `tagSize` | | hệ số cỡ tên vùng riêng vùng này, 0,5 đến 2 (thay `tagSize.zone`) | | `category` | `custom` | `project`, `residential`, `industrial`, `park`, `school`, `hospital`, `commercial`, `water`, `custom` | | `start`, `end` | | | | `spotlight` | false | vùng nổi bật: bản đồ ngoài vùng tối đi, viền trắng phát sáng, bóng đổ (vùng như được nhấc lên) | | `dimOut` | 0.65 | độ tối ngoài vùng khi `spotlight: true`, 0 đến 0.9; nhiều vùng nổi bật cùng lúc lấy mức cao nhất | | `grow` | | chỉ vùng tròn: số giây bán kính lan từ tâm ra khi hiện, 0.2 đến 5 (`true` = 1.2); bỏ trống thì hiện đủ ngay | | `labelAt` | | `[lng, lat]` (mọi loại vùng) = chỗ đặt tên, chỉ ghi khi muốn tên ở chỗ khác chỗ mặc định; vùng tròn còn nhận `edge` = tên nằm trên mép vòng (điểm phía bắc), hiện sau khi vòng lan gần xong. Không ghi thì tên đứng ở tâm hình học vòng ngoài chính (vùng tròn: tâm vòng; vùng có sẵn: phần đất liền, bỏ đảo nhỏ), cố định theo toạ độ nên máy quay lùi, tiến thì tên đứng yên giữa khối. Tên các vùng, vòng gần nhau tự né (cùng nhóm "vung": chỉ cần không đè; với tag điểm, tag tuyến, tên đường khác nhóm thì cách nửa chiều dài nhãn): chỗ mặc định bị chiếm thì dời trong lòng vùng, hết chỗ thì đứng sát ngoài vòng (trên, dưới, phải, trái); không cần ghi `labelAt` lệch tay cho từng vòng | | `image` | | ảnh phủ kín trong vùng, cắt đúng ranh (cờ, ảnh khu đất): `{ "file": "co.png" }` hoặc `{ "url": "..." }`, tuỳ chọn `opacity` 0 đến 1 (mặc định 1). Ảnh phủ cả khung bao vùng, cạnh thừa bị cắt; nằm trên nền màu vùng, dưới viền và tên. File ảnh để cạnh kịch bản như `images[]`; `url` từ web phải cho phép CORS | | `glow` | false | viền sáng: quầng màu vùng ôm quanh viền, bản đồ không tối đi (khác `spotlight`). Hợp vòng nút TOD, khu dự án cần nổi trên nền vệ tinh | | `glowK` | 1 | độ toả quầng sáng của `glow`, từ 1 đến 4: trên 1 thì thêm một quầng rộng mờ ngoài quầng thường. `theme: "vang-dem"` tự đặt 2,5 | | `streets` | false | đường trong vùng sáng: mọi đường xe chạy nằm trọn trong vùng vẽ màu vùng, có quầng (dữ liệu OpenFreeMap, dòng ghi nguồn tự thêm). `theme: "vang-dem"` tự bật | | `area` | | quy mô theo hồ sơ, số ha (vd `9.25`), hiện thành dòng thứ hai của tên vùng ("9,25 ha"); cần `showLabel: true`. Có số chính thức thì ghi `area`, đừng để tự tính | | `showArea` | false | tự tính quy mô từ hình vùng (tròn πr², đa giác trừ lỗ) và ghi dưới tên; trên 10.000 ha đổi sang km². Bị `area` đè | | `shortName` | | tên gọn khi máy quay lùi xa (vd vòng "1 Hóc Môn, Củ Chi" thì `"1"`): zoom xuống dưới `shortZoom` thì tên đầy đủ mờ ra, tên gọn mờ vào tại tâm vùng (qua khoảng 0,3 mức zoom, máy lùi 0,6 mức/giây thì khoảng 0,5 giây). Một vùng là đủ, không dựng vùng tàng hình mang chữ. Tên đầy đủ đang mờ ra nhường chỗ, không đẩy tên khác. Đổi theo zoom camera nên xem trước tua nhảy và xuất ra như nhau | | `shortZoom` | zoom lúc tên hiện trừ 0,5 | ngưỡng zoom đổi sang `shortName` (zoom camera của khổ gốc). Nhiều vòng cùng lùi thì ghi cùng một số để đổi cùng lúc, đặt cao hơn zoom lúc các tên bắt đầu dồn vào nhau | | `shortAt` | tâm vùng | `[lng, lat]` chỗ đặt tên gọn, như `labelAt` cho tên đầy đủ; ghi khi tâm vùng trùng biểu tượng điểm (vd lõi có điểm kim cương ở tâm) | | `labelDelay` | xem ghi chú | số giây sau `start` tên mới mờ vào (0,5 giây). Không ghi: vòng `grow` chờ 3/4 thời gian lan, vùng có `start` chờ 0,6 giây (rõ sau 1,1 giây), vùng từ đầu video hiện ngay. `0` = tên hiện cùng vùng. Vùng có tâm còn ngoài khung lúc hiện thì ghi trễ hơn để tên hiện khi máy quay đã tới | Nhiều phường, quận cùng lúc (vd các phường quanh dự án, các quận cũ): mỗi vùng một `preset`, `autoColor: "neighbor"`, `casing: true`, `fillOpacity` 0.3 đến 0.35, `width` khoảng 5, `showLabel: true`. So sánh loại đơn vị hay quy mô thì `autoColor: "type"` hoặc `"area"`. Vòng bán kính quanh ga, địa danh (vd 1 km, 3 km quanh ga metro): mỗi mức một vùng tròn cùng `center`, `name` là khoảng cách ("1 km"), `dash: true`, `dashMove: true`, `fillOpacity` khoảng 0.08, `showLabel: true`, `labelAt: "edge"`, `grow: 1.2`, vòng trong `start` trước, mỗi vòng sau trễ 0.6 giây. Thêm một điểm (`markers[]`) ở tâm mang tên ga hoặc địa danh, màu khác màu vòng (vòng vàng thì điểm `#f43f5e`). Cụm điểm, vòng gần nhau mà máy quay lùi ra xa (vd 5 cực vệ tinh quanh lõi TP HCM, lùi ra Côn Đảo): mọi chữ là tên vùng (một nhóm, chỉ cần không đè), không dùng tag điểm cho từng vòng; vòng nào lùi xa sẽ dồn vào cụm thì ghi `shortName` (số, tên ngắn) cùng `shortZoom`; vòng đứng xa (Côn Đảo) giữ tên đầy đủ. Tag điểm khác nhóm phải cách nửa chiều dài nhãn nên khi lùi xa tag sau bị ẩn (xem trước tua nhảy vẫn thấy); `validate_scene` báo những nhãn sẽ bị ẩn khi xuất. Nút TOD, khu đất đề xuất quanh ga (kiểu video tin metro): vùng tròn quanh nút giao (hoặc đa giác theo bản đồ quy hoạch), `color` #22d3ee, `fillOpacity` khoảng 0.22, `width` 4, `glow: true`, `showLabel: true`, `name` "Nút TOD đề xuất", `area` theo số công bố (ha). Không `grow`: vòng mờ vào cùng lúc camera dừng ở ga. Quy mô vẽ là minh hoạ, số ha lấy theo nguồn. ### `markers[]`: điểm | Trường | Mặc định | Ghi chú | |---|---|---| | `id` | `mk-N` | | | `kind` | `station` | `dot`, `station`, `plane`, `pin`, `card`, `diamond`, `train`; giá trị khác thành `station` | | `lng`, `lat` | | bắt buộc (trừ `train`) | | `label`, `sub` | | dòng chính, dòng phụ. Có `sub` thì tag thành hai dòng: tên trên, dòng phụ nhỏ dưới (vd `label` "Tên dự án", `sub` "Khu dân cư, phường") | | `color` | #ffffff | | | `ring` | true | chỉ `pin`: vòng sáng lan trên mặt đất quanh mũi ghim, chạy liên tục, nằm theo phối cảnh khi nghiêng máy. `false` để tắt | | `ringColor` | màu ghim | chỉ `pin`: màu vòng sáng, vd `#22d3ee` cho ghim đỏ | | `size` | 28 | cỡ biểu tượng | | `tagSize` | | hệ số cỡ tag riêng điểm này, 0,5 đến 2 (thay `tagSize.place`, với tag tiện ích thay `tagSize.amenity`) | | `tagZoom` | zoom lúc ghim hiện trừ 2 | chỉ `pin`: máy quay lùi xuống dưới mức zoom này thì tag tên dự án mờ dần rồi tạm ẩn (ghim, vòng sáng vẫn chạy nên vẫn thấy dự án), tiến lại thì hiện. `false` để luôn hiện. Tag tiện ích, điểm khác không ẩn. Tag điểm tự chọn chỗ không đè nét tuyến: dưới, trên, phải, trái biểu tượng rồi bốn góc chéo | | `target` | | chỉ `card`: tag tiện ích. `id` một vùng trong `zones[]` (chấm ở tâm vùng) hoặc `[lng, lat]`. Thẻ một dòng `label` (không hiện `sub`), chấm tròn ở đích, đường gạch đứt nối lên thẻ, hiện dần; không ghi `lng`, `lat` thì thẻ tự treo trên đích, sát mép khung thì tự dời vào. Xem `ke-chuyen.md`, mục tiện ích kề dự án | | `lift` | 170 | chỉ `card` có `target`: thẻ treo cao hơn đích bao nhiêu px (khung 1080) | | `group` | | nhóm né nhãn (chuỗi bất kỳ): tag điểm cùng group chỉ cần không đè, không phải cách nửa chiều dài nhãn như tag khác nhóm. Cụm điểm gần nhau (ga liền nhau, vệ tinh quanh lõi) cho chung một group để tag sau không tắt tag trước; `"vung"` = chung nhóm tên vùng | | `start`, `end` | | | Cách dùng: `pin` cho dự án chính, `plane` cho sân bay, `station` cho ga metro, nút giao, `dot` cho điểm phụ, `diamond` cho mốc đặc biệt, `card` cho thẻ thông tin có `label` + `sub`; `card` có `target` cho tag tiện ích kề dự án (một dòng, gạch đứt xuống lô). Tàu chạy (`train`): không cần toạ độ, cần `route` (id một tuyến) và `progress: [{"t": giây, "p": 0..1}]` là vị trí dọc tuyến theo thời gian. ### `images[]`: ảnh Ảnh do người dùng đưa (ảnh phối cảnh, ảnh thật của dự án, logo). Không tự tìm ảnh trên mạng. | Trường | Mặc định | Ghi chú | |---|---|---| | `id` | | | | `file` | | tên file ảnh; xuất bằng MCP trên máy thì đưa đường dẫn qua `assets` của `export_video`; mở trên web thì người dùng thêm ảnh vào dự án và lưu `.mvt` | | `url` | | hoặc địa chỉ ảnh `https://` (web cho phép tải) | | `marker` | | id một điểm: ảnh lấy toạ độ của điểm đó, treo ngay trên biểu tượng, viền trắng bo góc, mờ vào ra cùng điểm. Đây là cách gắn "tag ảnh" cho một vị trí | | `lng`, `lat` | | khi không có `marker`: ảnh căn giữa vào toạ độ | | `size` | 300 khi có `marker`, không thì 360 | chiều cao ảnh, px ở cạnh ngắn 1080 | | `frame` | | ảnh nổi: `"gold"` thay viền trắng bằng viền mỏng vàng chuyển sắc (hợp ảnh phối cảnh dự án cao cấp) | | `corners` | | 4 góc `[lng, lat]` theo thứ tự trên trái, trên phải, dưới phải, dưới trái: ảnh **nằm phẳng trên mặt đất** (mặt bằng dự án, sa bàn), nghiêng và xoay cùng máy quay, dưới vùng, tuyến và tag. Có `corners` thì `marker`, `lng`, `lat`, `size` bị bỏ qua | | `opacity` | 1 | chỉ cho ảnh có `corners`, 0 đến 1 | | `start`, `end` | | ảnh có `corners` mờ vào 0,6 s, mờ ra 0,4 s | Ví dụ: `{"id": "anh-ttg", "file": "tt-genesis.jpg", "marker": "ttg", "size": 280, "start": 3, "end": 9}`. Mặt bằng dự án trên bản đồ: cắt bỏ phần chú thích, logo, số điện thoại khỏi ảnh trước; lấy toạ độ góc bằng `get_road`, `find_place` theo đường, kênh rạch ghi trên mặt bằng, khớp hướng Bắc. `validate_scene` báo lỗi khi 4 góc xếp sai thành hình xoắn, cảnh báo khi lật gương. Ví dụ: `{"id": "mat-bang", "file": "mat-bang.jpg", "corners": [[106.7301, 10.7712], [106.7352, 10.7709], [106.7349, 10.7661], [106.7298, 10.7664]], "opacity": 0.9, "start": 6, "end": 12}`. ### `captions[]`: phụ đề Mỗi lúc chỉ hiện một caption: caption cuối cùng trong mảng có `start <= t <= end`. Không để caption chồng thời gian. Caption có `hook` thì phía trên là khối tiêu đề 3 dòng (dẫn `lead`, nhấn `hook`, bổ sung `extra`) theo bộ style đã duyệt, nằm trong khoảng 8% đến 30% chiều cao khung; `sub` là phụ đề (lời thoại) phía dưới. Luật hiện phụ đề (26/10/2026): câu có `hook` không hiện `sub` (như Nexus Video, khối tiêu đề thay phụ đề); 3 giây đầu clip không hiện `sub`, câu đang chạy thì `sub` mờ hiện từ giây 3. Vẫn nên ghi `sub` đủ cho mọi câu (lời đọc, làm phụ đề ở nơi khác). Họ màu cả clip: `titleColor` ở gốc kịch bản, một trong 12 họ (xem `get_guide` chủ đề `typo`); **thường bỏ trống**: web tự bốc theo kịch bản, vàng gold 30 %, 70 % chia đều 11 họ còn lại, nên mỗi clip một màu. Chỉ ghi khi người dùng muốn một màu; `titleStyle` cũng vậy. Viền chữ phụ đề: `vienPhuDe` (mặc định xanh lá). Nền sau tiêu đề: `nen` ở gốc kịch bản hoặc ở caption, `"sang"` (chữ viền, bóng đậm) hoặc `"toi"` (tắt); không ghi thì web tự bật `"sang"` trên nền bản đồ sáng. `hookColor`, `hookStyle` không còn dùng. Khổ 9:16, 3 giây đầu: web tự gom badge, khối tiêu đề và phụ đề vào vùng TikTok không che (dưới thanh tab và hộp quà, trên tên kênh và mô tả, tránh cột nút bên phải), né ghim dự án, phụ đề câu đầu ngắt dòng hẹp hơn; từ giây 3 chữ trượt dần 0,8 giây về chỗ thường. Không cần ghi gì; muốn tắt thì ghi `"openLayout": false` ở gốc kịch bản. | Trường | Ghi chú | |---|---| | `start`, `end` | | | `lead` | dòng dẫn của tiêu đề (nhỏ, vd "Chỉ", "Hơn", "Mặt tiền") | | `hook` | dòng nhấn (to nhất, in hoa), tối đa khoảng 12 ký tự: số + đơn vị ("2 PHÚT", "70%", "600 TRIỆU") hoặc tên ("VÕ CHÍ CÔNG") | | `extra` | dòng bổ sung dưới dòng nhấn (vd "ra nút giao Liên Phường"); `từ` là từ khoá tô màu ở style M9 | | `lead2`, `doiLuc` | đổi dòng dẫn (style M16): `lead2` là dòng dẫn thứ hai (viết thường, cần `lead`), thay `lead` lúc `doiLuc` (giây tính từ đầu caption, từ 0,6 s và trước lúc caption hết ít nhất 1 s); dòng nhấn đứng yên. Caption có `lead2` web tự lấy M16; web không tự lấy M16 cho caption khác, ghi tay `titleStyle: "M16"` thì caption một dòng dẫn cũng được (dòng dẫn đứng yên) | | `mauNhan` | dải màu dòng nhấn M16: `kem-dao` (mặc định), `vang-cam`, `dao-hong`, `xanh-duong`, `mint-la`, `champagne`, `hong-tim`, `bac-xanh`, `cam-do`, `hong-dao`. Style khác bỏ qua; mã lạ `validate_scene` báo lỗi. Chọn theo nền: xem `get_guide` chủ đề `typo` | | `titleStyle` | style tiêu đề của câu: `M3`, `M6`, `M7`, `M8`, `M9`, `M11`, `M12`, `M14`, `M16`; bỏ trống thì web tự chọn theo luật (tối đa 3 style mỗi clip, không lặp liền nhau); luật đủ ở `get_guide` chủ đề `typo` (file `skill/references/typo.md`), ghi tay trái luật thì `validate_scene` cảnh báo | | `titleBg` | chữ nền lớn của style M8 (mặc định `hud.tag`; là tên dự án đầy đủ in hoa, không rút gọn, không cắt bớt chữ trong tên, tên dài thì chữ nền tự thu; ghi một phần cắt của tên dự án thì `validate_scene` báo lỗi). Cảnh M8 không nhắc lại tên dự án ở `lead`, `lead2`, `hook`, `extra` (chữ nền đã là tên): ghi tay M8 mà nhắc lại thì `validate_scene` báo lỗi | | `sub` | câu lời đọc đầy đủ, tối đa khoảng 100 ký tự | | `highlight`, `highlightColor` | các cụm trong `sub` được tô màu | | `note` | dòng nhỏ phía dưới | | `tag`, `tagColor` | nhãn riêng của caption này (thay `hud.tag`) | | `vienPhuDe` | màu viền phụ đề riêng câu này (thay `vienPhuDe` của kịch bản) | ### `legends[]`: chú giải `{"title", "subtitle", "rows": [{"color", "label", "sub", "shape"}], "start", "end"}`. `shape`: `line`, `dash`, `hatch`, `area`, bỏ trống là chấm tròn. Tối đa khoảng 6 dòng. `"auto": true` thì web tự sinh dòng từ các tuyến, vùng đang hiện. ### `texts[]`: chữ phủ | Trường | Ghi chú | |---|---| | `content` | nội dung; với `price-card` dòng đầu là tên, các dòng sau là thân | | `style` | `title-gold` (mặc định), `subtitle-white`, `label-dark`, `caption-box`, `price-card` | | `anchor` | `screen` (mặc định) hoặc `map` (cần `lng`, `lat`, tuỳ chọn `altitude`) | | `position` | `top`, `center`, `bottom` (mặc định) | | `size` | hệ số cỡ, mặc định 1 | Chữ phủ neo bản đồ không phải tag: không né nhau, không né tag khác, không có viền màu, chấm đích và đường gạch đứt như tag tiện ích. Không dùng `texts` (kể cả `caption-box`, `label-dark`) để thay tag điểm, tag tiện ích hay để có chữ tag to hơn. Muốn tag to thì giữ `markers` (ghim, `card` có `target`) và ghi `tagSize`, ví dụ `{"amenity": 1.5}`. Nhiều mốc thời gian (hiện tại, 2027, 2030) thì mỗi mốc một tag tiện ích hoặc một bảng `legends`, không xếp nhiều hộp chữ chồng lên nhau. ### `ctas[]`: khung kêu gọi `{"title", "subtitle", "color": "#facc15", "textColor": "#1c1917", "y": 0.09, "start", "end"}`. `y` là khoảng cách từ mép trên khung (phần của chiều cao). Khổ dọc dùng câu kêu gọi trong ứng dụng (vd "Nhắn tin để được tư vấn"); liên hệ theo quy tắc 4 cuối file. Web tự dời khung kêu gọi, chữ phủ, phụ đề để không đè nhau. ### `tour`: bay dọc tuyến metro (tuỳ chọn) Một object ở gốc kịch bản, giống hệt thứ nút "Bay dọc tuyến" (tab Camera) của web ghi ra. Web tự sinh: tổng quan cả tuyến kèm thẻ số liệu, bổ nhào xuống ga đầu, camera chạy sát mặt đất dọc tuyến và dừng ở từng ga, ga đánh số (đĩa màu tuyến, chân cắm xuống tuyến, tên bên phải), đoàn tàu 3 toa chạy trên tuyến, thẻ ga có km chạy ("Km 12,59 / 32,15"), chip tên tuyến, bản đồ nhỏ tiến trình ("Đã đi 39%, còn 19,6 km"), thanh ga, cuối cùng lùi ra cả tuyến. Trong khoảng bay, keyframe `camera[]` bị bỏ và tiêu đề `hud.badge`, `hud.title` ẩn đi. | Trường | Mặc định | Ghi chú | |---|---|---| | `route` | | bắt buộc: id một tuyến trong `routes[]` có ga (tuyến metro có sẵn `preset` mang sẵn `stations`, xem `list_library_routes`) | | `from`, `to` | ga đầu, ga cuối | tên ga (như `stations` của `list_library_routes`) hoặc chỉ số (0 = ga đầu tuyến, -1 = ga cuối); `from` sau `to` thì bay ngược chiều tuyến; `from` = `to` là kịch bản tập trung một ga (tàu chạy vào, dừng, chạy đi) | | `start` | 0 | giây bắt đầu chuyến bay | | `intro` | 6 | giây tổng quan đầu (0 = bỏ tổng quan và bổ nhào) | | `dive` | 3 | giây bổ nhào từ tổng quan xuống ga đầu | | `dwell` | 5 | giây dừng ở mỗi ga | | `pace` | 3.5 | giây chạy cho mỗi km giữa hai ga, kẹp trong 2,5 đến 9 giây mỗi chặng | | `outro` | 4 | giây lùi ra cả tuyến cuối chuyến (0 = bỏ) | | `zoom`, `pitch` | 16.2, 48 | góc máy sát mặt đất | | `title` | tên tuyến | tên trên chip và thẻ mở đầu | | `sub` | "N GA, ga đầu - ga cuối" | dòng dưới tên | | `stats` | km, số nhà ga | thẻ mở đầu: tối đa 3 `{"value": "Hơn 30 km"}` hoặc `{"value": "19", "label": "nhà ga"}` (có label thì số tô đỏ) | | `foot` | | dòng nhỏ cuối thẻ mở đầu, vd "7 phường, trên cao" | | `stations` | | thông tin từng ga, ghép theo `name`: `note` (địa chỉ ngắn), `tags` (tối đa 3, vd "Trên cao"), `transfer` (`[{"name", "color"}]` tuyến trung chuyển), `code` (chữ trong đĩa thay số thứ tự, vd "M1"), `label` (tên hiện thay tên thư viện), `dwell`, `skip: true` (bỏ ga). Tuyến tự vẽ không có ga thì ghi `lng`, `lat` để thêm ga (cách tuyến tối đa 150 m) | | `say`, `voice` | | câu lời đọc mở đầu (lúc tổng quan) và id mục `audio[]` (kind `voice`) đọc câu đó; mỗi ga trong `stations` cũng có `say`, `voice` riêng | | `hud`, `train`, `numbered`, `caps` | true | `false` để tắt HUD bay, đoàn tàu, ga đánh số, phụ đề lời đọc | `validate_scene` báo giây kết thúc chuyến bay (đặt `duration` ít nhất bằng số đó) và ghi vào storyboard từng mốc "dừng ga N": đặt câu lời đọc, phụ đề về ga N bắt đầu đúng giây đó. Muốn mỗi ga dài theo câu đọc thì đặt `dwell` riêng của ga trong `stations`. **Lời đọc khớp ga** (`say`): câu đọc lúc camera tới ga, hiện kèm làm phụ đề tầng dưới (khi không có `captions[]` nào đang chạy). Giây dừng ga tự giãn cho đủ câu: 0,3 giây trước câu, cả câu, 0,7 giây sau câu; tổng quan mở đầu giãn theo `tour.say` như vậy. Độ dài câu lấy từ `dur` của file tiếng (`audio[]` có id bằng `voice`), chưa có file thì ước theo số chữ. Câu nên ngắn (dưới 12 giây đọc, khoảng 35 chữ). Có file tiếng thì web và MCP đặt `start`, `end` của mục `audio[]` đó đúng giây camera dừng ở ga, không cần tự tính. Tạo file tiếng: bản MCP chạy trên máy có `make_voice` đọc mọi câu `say` bằng Google Cloud Text-to-Speech (giọng Chirp 3 HD tiếng Việt, khoá của người dùng ở biến môi trường `GOOGLE_TTS_KEY`, miễn phí 1 triệu ký tự mỗi tháng), lưu WAV cạnh kịch bản, tự gọn lời cho liền (cắt lặng đầu, cuối, chỗ nghỉ dài hơn 0,3 giây rút còn 0,26 giây; `audio[].file` là bản `.gon.wav`, file Google gốc giữ cạnh đó), gắn `audio[]`, `voice`, khớp giây và nới `duration`. Giọng: `Erinome` (mặc định, nữ), `Kore`, `Aoede`, `Leda` (nữ), `Charon`, `Puck` (nam)... Không có khoá thì người dùng tự tải file tiếng từng câu lên web (bảng Âm thanh, tab Dự án) rồi chọn ở ô Lời đọc của ga, hoặc ghi `audio[]` kèm `voice` như trên. ### `scenes[]`: chia cảnh (tuỳ chọn) `{"id", "name", "start", "basemap", "transition", "tDur"}`. Web nối các cảnh liền nhau từ 0 tới hết video (cảnh đầu luôn bắt đầu ở 0, `end` tự tính). `basemap` đổi nền riêng cho cảnh; `transition`: `black` (mờ qua đen) hoặc `white` (loé trắng), `tDur` 0.2 đến 3 giây. Cảnh giúp người dùng sửa từng đoạn trên timeline; không bắt buộc. ### `audio[]`: âm thanh (tuỳ chọn) | Trường | Mặc định | Ghi chú | |---|---|---| | `kind` | `voice` | `voice` (lời đọc), `music` (nhạc nền), `sfx` (hiệu ứng có sẵn) | | `file` / `url` / `sfx` | | file trong dự án .mvt, địa chỉ file, hoặc hiệu ứng có sẵn: `pop` (bật), `whoosh` (vút), `swish` (lướt), `tick` (tích), `ding` (chuông), `luot` (lướt gió), `gio-dai` (gió dài 1,6 giây) | | `start`, `end` | 0, hết file | giây trên video; `end` cắt bớt | | `volume` | voice 1, music 0.35, sfx 0.7 | 0 đến 1.5 | | `fadeIn`, `fadeOut` | | giây mờ vào, mờ ra | | `loop` | false | chỉ nhạc nền: lặp lại tới `end` | | `offset` | 0 | giây cắt đầu file; nhạc nền ghi `"auto"` thì web cắt cho drop đầu rơi giữa clip, bắt vào đầu ô nhịp | | `nhac` | | số đo nhạc (nhịp, đoạn, drop, độ to) web tự ghi khi tải nhạc lên; không cần viết tay | | `dur` | | giây dài của file (lời đọc); `make_voice` và web tự ghi, bay dọc tuyến dùng để giãn giây dừng ga | **Nhạc nền mặc định**: kịch bản không có mục `kind: "music"` thì web tự thêm nhạc The Violins (cắt đầu tự động, lặp tới hết video). Người dùng dặn không để nhạc thì ghi `music: false` ở gốc kịch bản. Có lời đọc thì nhạc nền tự nhỏ đi 10 dB trong lúc đọc. Nhạc tải lên được đo độ to và đưa về cùng mức với nhạc mặc định. Cấp kịch bản: `sfxAuto` (mặc định bật, `false` để tắt) tự thêm tiếng theo chuyển động, ưu tiên từ cao xuống: câu có tiêu đề (hook) kêu bộ tiếng bung tiêu đề của Nexus Typo (`bo1`, mỗi dòng khối một tiếng), chuông `ding` lúc thẻ kênh cuối hiện, tuyến bắt đầu vẽ kêu lướt gió `luot` (`drawTime` dưới 2 giây) hay gió dài `gio-dai` (từ 2 giây, kể cả không ghi `drawTime`, mặc định 3), trừ hiệu ứng `pulse`, `breathe`, `static`; vút `whoosh` vùng hiện, bật `pop` ghim (`kind: pin`) hiện, tích `tick` câu phụ đề thường và ga dừng khi bay dọc tuyến. Luật H31: 1,5 giây trước tiếng tiêu đề đầu và sau tiếng tiêu đề cuối của khối không có tiếng tự động khác (trừ tiếng ở đầu clip), nên tuyến, vùng, ghim, chuông bắt đầu sát câu có tiêu đề sẽ im. Hai tiếng cách nhau dưới 0,6 giây thì gộp, giữ tiếng ưu tiên cao; tối đa 8 tiếng mỗi 18 giây (khối tiêu đề tính một). `sfxVolume` 0 đến 1 (mặc định 0.6): ở 0.6 tiếng của Map có đỉnh khoảng −20 dBFS (chuông −21, vùng −22,5), nhỏ hơn tiếng Nexus Typo một nửa; tiếng tiêu đề kêu mức Typo (−15 đến −20 dBFS); tăng giảm thì chỉnh tương đối quanh mức đó. Thiếu trường này thì vẫn bật. File .json không chứa file âm thanh, chỉ .mvt nhúng kèm (nhạc mặc định có sẵn trên web). MP4 xuất ra có tiếng AAC (máy không có thì Opus), cả dải tiếng được đưa về −14 LUFS, đỉnh tối đa −1 dBTP. `validate_scene` ghi nhạc nền và từng tiếng tự động vào storyboard. ### `link`: nối clip vào clip khác (tuỳ chọn) Mọi lớp có thời gian (keyframe `camera[]`, `captions[]`, `texts[]`, `legends[]`, `ctas[]`, `images[]`, `models[]`, `routes[]`, `zones[]`, `markers[]`, `audio[]`) gọi là clip, nối được vào một clip khác bằng trường `link`. Dời clip đích (sửa `start`, đổi lời đọc làm câu dài ra) thì clip nối đi theo, giữ độ dài; không phải tính lại giây từng lớp. `scenes[]` không nối được. | Trường | Mặc định | Nghĩa | |---|---|---| | `link.to` | | `id` của clip đích (cả hai clip phải có `id`; mục chưa có `id` thì đặt, vd `"cap-1"`, `"cam-2"`) | | `link.edge` | `start` | `start` = nối vào mép đầu clip đích, `end` = mép cuối | | `link.word` | | nối vào lúc chữ này được đọc trong clip đích (thay cho `edge`): clip đích có `words: [{ "w": "500", "t": 1.4 }]` (giây tính từ đầu clip) thì lấy đúng; không có thì ước theo số tiếng trong chữ của clip (`lead`, `hook`, `extra`, `sub`); không thấy chữ thì về mép đầu | | `link.offset` | 0 | giây lệch sau mốc (âm = trước mốc) | Web và `validate_scene` tính lại `start`, `end` (keyframe: `t`) theo `link` mỗi lần đọc, kẹp trong 0 đến `duration`; file vẫn ghi giây tuyệt đối nên công cụ khác không biết `link` vẫn đọc đúng. Nối vòng (A nối B, B nối A) là lỗi; nối vào id không có, chữ không thấy là cảnh báo, clip đứng yên ở giây đã ghi. Ví dụ: phụ đề vào lúc lời đọc bắt đầu, ghim trường bật lúc đọc tới "500 mét", tuyến vẽ khi phụ đề hết: ```json "audio": [{ "id": "loi-3", "kind": "voice", "file": "cau-3.wav", "start": 12, "end": 16.5 }], "captions": [{ "id": "cap-3", "hook": "CỤM TRƯỜNG", "sub": "Cụm trường học trong 500 mét", "start": 12, "end": 16.5, "link": { "to": "loi-3" } }], "markers": [{ "id": "truong", "kind": "card", "label": "Trường Ánh Sao", "start": 13.6, "end": 18, "link": { "to": "cap-3", "word": "500 mét" } }], "routes": [{ "id": "duong-1", "start": 16.5, "end": 20, "link": { "to": "cap-3", "edge": "end" } }] ``` Trên web: clip nối có vạch vàng bên trái và vạch nối tới mốc; kéo clip đích thì clip nối đi theo; kéo clip nối thì giữ nối, lệch mới; giữ Ctrl lúc thả clip lên clip khác để nối; bấm vạch nối hoặc giữ Alt lúc kéo để gỡ nối. ### Quy tắc riêng của tool này 1. **Không đoán toạ độ thật.** Mọi `lng`, `lat`, `points` lấy từ `find_place`, `get_road`, `list_library_routes`, `list_library_zones` hoặc do người dùng đưa. Không tìm được thì hỏi người dùng. 2. **Tuyến quy hoạch đánh dấu `approx: true`** (hoặc `kind: "planned"`, tự có approx) và `hud.disclaimer` phải có chữ "minh hoạ", vd "Hướng tuyến minh hoạ theo quy hoạch công bố". `validate_scene` báo lỗi nếu thiếu. 3. **Chữ hiển thị không dùng dấu chấm giữa (U+00B7), gạch dài (U+2014), gạch ngang vừa (U+2013).** Thay bằng dấu phẩy, dấu chấm hoặc gạch nối thường "-". Áp dụng cho mọi trường hiện lên video: hud, captions, markers, routes (`name`, `label`, `legendLabel`), zones, legends, texts, ctas. Tên tuyến trong thư viện có gạch ngang vừa, nên tự viết lại `name`. 4. **Liên hệ trên hình.** Zalo, địa chỉ web, mã QR không gắn lên video ở khổ nào. Số điện thoại chỉ ghi ở bản ngang 16:9; khổ 9:16, 1:1 không ghi (TikTok, Reels cấm). Áp dụng cho mọi trường hiện lên video (hud, outro, captions, markers, routes, zones, legends, texts, ctas), trừ `hud.source`. `validate_scene` cảnh báo. ## Kể chuyện bằng bản đồ: từ bài tin tới video 30 đến 60 giây Người xem lướt Reels, TikTok quyết định ở lại hay đi trong 2 giây đầu. Video bản đồ giữ người xem bằng **một câu hỏi rõ** (tuyến này đi đâu, dự án này gần gì) và **trả lời bằng hình** (tuyến vẽ dần, camera bay theo). ### Bước 1: rút ý từ bài tin Đọc bài, ghi ra năm thứ: 1. **Tin chính trong một câu**: "Metro số 6 sắp khởi công, nối Tân Sơn Nhất với Phú Hữu". 2. **Đối tượng trên bản đồ**: tuyến nào, ga nào, dự án nào, sân bay, cầu, nút giao. 3. **Con số**: chiều dài, số ga, vốn, năm khởi công, năm xong. 4. **Ai được lợi**: khu vực, dự án nằm gần tuyến (đây thường là lý do người làm BĐS kể chuyện này). 5. **Mức chắc chắn**: đã khai thác, đang thi công hay còn là quy hoạch. Quyết định `kind` và có cần chữ "minh hoạ" không. Không đưa lên video con số bài báo không có. Bài ghi "dự kiến", "đề xuất" thì video cũng giữ đúng mức đó. ### Bước 2: chọn khung kể | Khung | Hợp với | Mạch | |---|---|---| | A. Tuyến mới | tin khởi công, thông xe một tuyến | toàn cảnh, vẽ tuyến từ đầu tới cuối, dừng ở 2 đến 3 ga chính, chú giải, kết | | B. Dự án và hạ tầng quanh nó | giới thiệu dự án BĐS | bay vào dự án, lần lượt hiện từng tuyến kèm khoảng cách, kéo ra toàn cảnh, CTA | | C. Trước và sau | tuyến nối hai nơi trước đây đi lâu | hiện đường đi cũ, rồi tuyến mới, so thời gian | | D. Mạng lưới | quy hoạch nhiều tuyến | từng tuyến xuất hiện theo màu, chú giải tổng | | E. Một điểm nóng | nút giao, cầu, sân bay | zoom sát, xoay camera quanh điểm, thẻ thông tin | ### Bước 3: dàn nhịp Một video 45 đến 55 giây thường có 4 đến 6 cảnh: | Đoạn | Thời lượng | Việc | |---|---|---| | Mở | 0 đến 7 giây | `hud.badge` + `hud.title`, camera toàn cảnh, caption có `hook` gây tò mò | | Thân | 3 đến 4 cảnh, mỗi cảnh 8 đến 12 giây | mỗi cảnh một ý: một tuyến hoặc một điểm; tuyến vẽ trong 3 đến 5 giây, nhãn hiện sau khi vẽ | | Kết | 5 đến 8 giây | kéo ra toàn cảnh, chú giải hoặc CTA | Gợi ý góc quay: - **Nghiêng máy (`pitch`) tối đa 30 độ** ở mọi cảnh. Máy thấp hơn trông 3D hơn nhưng đường, nhãn ở xa bị nén, khó đọc trên điện thoại. Chỉ vượt 30 khi người dùng yêu cầu. - Toàn cảnh: zoom 10 đến 11, pitch 0 đến 15. - Theo tuyến: zoom 12 đến 13, pitch 20 đến 30, `bearing` xoay theo hướng tuyến. - Sát điểm: zoom 14 đến 16, pitch 25 đến 30. - Mỗi cảnh xoay `bearing` thêm khoảng 20 đến 45 độ cho có chuyển động; keyframe cách nhau 2 đến 3 giây. - Kết bằng vài giây quay chậm quanh dự án (đổi `bearing`, giữ zoom) rồi kéo ra. - Chuyển giữa hai nơi xa: kéo ra zoom thấp ở giữa rồi zoom vào, đừng bay ngang ở zoom cao. Gợi ý cho điểm dự án: - Dùng `pin` (có sẵn vòng sáng lan dưới ghim), `label` là tên dự án, `sub` là khu, phường (tag hai dòng). - **Hỏi người dùng có ảnh của vị trí không** (ảnh phối cảnh, ảnh thật). Có thì gắn làm tag ảnh: `images[]` với `marker` là id của ghim, hiện vài giây lúc camera tới dự án. Không có thì bỏ qua, đừng lấy ảnh trên mạng. - Tuyến ghi `"flow": true, "dash": true` (nét đứt chạy), giống tuyến mới tạo trên web. **Caption nói gì, bản đồ chỉ nấy.** Chữ trên màn hình nêu một đặc điểm nhìn thấy được trên bản đồ (mặt tiền, giáp sông, sát ga) thì trong lúc caption đó chạy bản đồ phải chỉ ra đúng chỗ ấy, không để chữ chạy một mình. Ví dụ "4 mặt tiền": - Máy quay lùi ra cho thấy trọn khu đất và cả 4 mặt ở vùng 3: zoom thấp hơn cảnh sát điểm 1 đến 2 bậc, pitch từ 15 trở xuống, tâm ở giữa khu đất. - Mỗi mặt tiền một tuyến ngắn chỉ vẽ đoạn giáp khu đất, không vẽ cả con đường: mặt giáp đường `"kind": "highlight"`, mặt giáp sông `"color": "#38bdf8"`; mỗi tuyến có `label` (tên đường, tên sông). - Các tuyến `start` lần lượt cách nhau khoảng 0,6 giây từ lúc caption hiện, `drawTime` 0,8 đến 1,2 giây, để người xem đếm được từng mặt. - Toạ độ ranh khu đất và đoạn giáp sông **hỏi người dùng** (hoặc lấy đường bằng `get_road` rồi cắt đúng đoạn giáp), không đoán. - `validate_scene` cảnh báo khi caption ghi "N mặt tiền" (hoặc "N mặt giáp") mà không có đủ N tuyến hiện ra cùng caption, hoặc máy quay lúc vẽ xong chưa thấy trọn các tuyến đó. **Tiện ích kề dự án: tô lô, tag tiện ích.** Kiểu video mẫu "bước xuống là siêu thị GO!, bệnh viện Hoàn Mỹ": máy quay sát dự án, từng lô tiện ích kế bên tô màu, tag tên treo trên lô nối bằng đường gạch đứt. - **Ưu tiên kịch bản.** Chỉ vẽ tiện ích mà kịch bản (lời đọc, caption) nhắc tới, và chỉ ở cảnh có khung gần dự án thấy được cả dự án lẫn lô tiện ích (zoom khoảng 15,5 đến 17, pitch 25 đến 30). Kịch bản không nhắc thì không tự thêm, dù tiện ích nằm ngay cạnh. Tiện ích xa (vài km) thì không tô lô, dùng tuyến, ghim như thường. - **Toạ độ: hỏi người order trước.** Hỏi một lần cho mọi tiện ích cần vẽ, kèm hướng dẫn: Google Maps trên máy tính nhấp chuột phải vào giữa khu đất của tiện ích, dòng đầu là toạ độ, bấm là chép; điện thoại nhấn giữ giữa khu đất để thả ghim rồi chép toạ độ. Nói rõ: "3 phút không có trả lời thì em tự đo, tự vẽ". - **3 phút không có phản hồi thì tự đo, tự vẽ**: `find_lot` với `near` là toạ độ dự án, `name` là tên trong kịch bản; chọn lô `distance_m` nhỏ, tên khớp. Claude Code: hỏi xong thì chạy nền một lệnh chờ 180 giây (Bash `sleep 180`, `run_in_background`) để được gọi lại; nơi không hẹn giờ được (chat trên web, Desktop) thì lượt sau mà vẫn chưa có toạ độ là tự đo. Tự đo thì báo trong lời nhắn (tên lô trên bản đồ, khoảng cách), không ghi lên hình. - Người order đưa toạ độ một điểm thì vẫn gọi `find_lot` (`near` là điểm đó, `radius` 150) để lấy ranh lô chứa điểm ấy (`distance_m` 0). Bản đồ không có ranh thì vòng tròn quanh điểm, bán kính theo ảnh vệ tinh. - **Lô**: dán `zone` của `find_lot` vào `zones[]`, đặt `id`, không ghi `color` (với `theme: "ba-vai"` web tô mọi lô tiện ích màu lạnh, khu dự án màu ấm; chỉ khi kịch bản không dùng theme mới ghi mỗi tiện ích một màu khác màu dự án, vd siêu thị `#f43f5e`, bệnh viện `#38bdf8`, trường `#a3e635`), `fillOpacity` 0,35 đến 0,4, `width` 4, `glow: true`, `start` theo lời đọc. Tên lô để ở tag, không bật `showLabel`. `name` theo kịch bản, không lấy tên trên OpenStreetMap (OSM ghi "Bệnh viện Hoàn Mỹ Thủ Đức", "GO! Dĩ An", thương hiệu cũ Big C). - **Tag tiện ích**: `markers[]` `kind: "card"`, `target` là `id` của lô, `label` **một dòng** tên gọn ("Siêu thị GO!", "BV Quốc tế Hoàn Mỹ"), không `sub`, không nhãn phụ phía trên; có ghi `color` cho lô thì thẻ ghi trùng màu đó; `start` sau lô 0,2 đến 0,3 giây. Không ghi `lng`, `lat`: thẻ tự treo trên lô, chấm tròn ở giữa lô, đường gạch đứt nối lên thẻ, hiện dần (chấm, đường, rồi thẻ mở từ giữa trong 0,9 giây). Sát mép khung thì thẻ tự dời vào trong, không gãy dòng; khổ dọc chừa cột nút bên phải. Thẻ cao quá hay thấp quá thì chỉnh `lift`. - Nhiều tiện ích: lần lượt cách nhau 0,6 đến 1 giây, tối đa 3 đến 4 tag cùng khung. Mỗi tag hiện ít nhất 3,9 giây (0,9 giây mở ra, 3 giây đứng yên). Khoảng cách, mô tả ("ngay sát bên phải", "bước xuống nhà") để ở caption, không nhét vào tag. ### Bước 4: phụ đề Mỗi caption ứng với một câu lời đọc. Có hai kiểu: **Câu có tiêu đề** (câu mang con số, tên riêng, ý chính): web vẽ khối tiêu đề ba dòng và **không hiện `sub`**, nên mọi ý cần đọc phải nằm trong ba dòng này. - `hook`: dòng nhấn, 2 đến 4 chữ đắt nhất của câu, in hoa, nên trong khoảng 12 ký tự ("45 KM", "8 GA NGẦM", "QUÝ 4 2026"); quá 20 ký tự thì `validate_scene` cảnh báo. Ưu tiên con số, rồi tên riêng. - `lead`: dòng dẫn phía trên, viết thường ("Chỉ", "Cách", "Metro dài khoảng"). - `extra`: dòng bổ sung phía dưới, viết thường ("với 31 nhà ga", "ra nút giao Liên Phường"). - `loai`: loại chi tiết (`thoi-gian`, `khoang-cach`, `quy-mo`, `gia`, `moc`, `ten`, `khac`) để web chọn style đúng; không ghi thì web đoán theo `hook`. - `sub` vẫn ghi câu lời đọc (để người dùng sửa, đổi kiểu sau), nhưng không lên hình ở câu này. - Không ghi `titleStyle`, `titleColor`: web tự bốc. Bảng chọn dòng nhấn và luật style ở `typo.md`. **Câu thường** (câu nối, câu giải thích, không có `hook`): chỉ hiện phụ đề. - `sub`: câu lời đọc, gọn lại còn tối đa khoảng 100 ký tự. - `highlight`: các cụm trong `sub` cần tô màu, thường là con số và tên riêng; phải chép đúng từng chữ có trong `sub`. Caption nối tiếp nhau, không chồng thời gian. Lời đọc dài thì chia thành nhiều caption ngắn. Câu 3 dòng nên dài từ 3,4 giây, 2 dòng từ 2,2 giây. 3 giây đầu clip web không hiện phụ đề (khổ 9:16 gom tiêu đề vào giữa khung), nên câu mở đầu phải là câu có tiêu đề, ngắn. ### Bước 5: chữ trung thực - Không ghi "vị trí gần đúng" lên hình (`sub` của marker, disclaimer, caption): bộ kiểm báo lỗi. Vị trí dự án ước theo bài báo thì báo người dùng tự kiểm. - Hướng tuyến chưa có bản vẽ chính thức: `approx: true` hoặc `kind: "planned"`, disclaimer có "minh hoạ". - Nêu nguồn trong `hud.source` hoặc disclaimer khi bài tin có nguồn rõ; ghi tên báo, cơ quan ("Theo Sở Xây dựng"), không ghi địa chỉ web. - Liên hệ: Zalo, địa chỉ web, mã QR không gắn lên video ở khổ nào; số điện thoại chỉ ở bản ngang 16:9. CTA khổ dọc dùng câu kêu gọi trong ứng dụng ("Nhắn tin để được tư vấn"). `validate_scene` cảnh báo. ### Lỗi hay gặp - Một dự án hai tag tên: ghim dự án đã ghi tên thì không thêm thẻ, tên tuyến hay tên vùng ghi lại đúng tên đó cùng lúc (`validate_scene` cảnh báo). Muốn khoanh khu đất dự án thì vùng để `showLabel: false`. - Tự thêm chữ người dùng không đưa: tên công ty, tên sàn, tên tài khoản (`hud.author`), tag địa điểm không có trong lời đọc. Mọi chữ trên hình phải từ kịch bản lời đọc hoặc từ người dùng. - Nhắc tới vành đai (Vành đai 1, 2, 3, 4) mà chỉ vẽ một khúc: người xem tưởng vành đai chỉ có vậy. Lời đọc nhắc vành đai thì chạy hết tuyến bằng tuyến có sẵn (`"preset": "vanh-dai-3"`, `"points": []`; Vành đai 2, 3 TP.HCM khép kín cả vòng, Vành đai 4 tới Hiệp Phước, Vành đai 1 là cung trong Vành đai 2), muốn nhấn khúc gần dự án thì thêm tuyến `of` cắt đoạn đó. Tự vẽ hay tìm OSM tên vành đai mà ngắn hẳn cả tuyến thì `validate_scene` cảnh báo. - Máy quay đứng (giữ khung) mà cụm nội dung lệch một bên hoặc lùi quá xa, khung thừa đất trống: lúc giữ khung, cụm ghim, tag và tuyến mới vẽ phải nằm giữa vùng 3 (30% đến 79% chiều cao) và zoom sát nhất mà cả cụm còn vừa. Tuyến ló ra ngoài khung hoặc dài phủ quá nửa vùng 3 (trục đường, metro dẫn mắt) không tính vào cụm, có nó thì không ép zoom sát hơn. `validate_scene` cảnh báo kèm lng, lat, zoom gợi ý cho hai keyframe của quãng (giữ pitch, bearing); trên web bấm "Căn giữa nội dung" trong bảng Camera. - Bật mọi thứ ngay giây 0: người xem không biết nhìn đâu. Cho từng lớp xuất hiện theo lời đọc. - Zoom quá nhanh giữa hai keyframe gần nhau: `validate_scene` cảnh báo khi quá 0,8 bậc mỗi giây. - Nhãn chữ nhỏ trên video dọc: giữ `labelSize` từ 32 trở lên. - Tên tuyến chép từ thư viện còn gạch ngang vừa: viết lại bằng "-". - Quên disclaimer cho tuyến quy hoạch: `validate_scene` báo lỗi. - Caption nêu đặc điểm (4 mặt tiền, view sông) mà bản đồ đứng yên, máy quay vẫn sát: xem mục "Caption nói gì, bản đồ chỉ nấy" ở bước 3. - Tag tiện ích hai dòng, có nhãn phụ, hoặc tự thêm tiện ích kịch bản không nhắc: xem mục "Tiện ích kề dự án" ở bước 3. ## Khung mẫu và đoạn trích Bắt đầu kịch bản mới từ khung tối thiểu, rồi thêm từng phần theo các đoạn trích bên dưới. Toạ độ trong file này là số giả để thấy cấu trúc; kịch bản thật lấy toạ độ từ công cụ hoặc từ người dùng (quy tắc 1 trong SKILL.md). ### Khung tối thiểu ```json { "version": 1, "format": "9:16", "duration": 30, "basemap": "satellite-soft", "theme": "ba-vai", "hud": { "badge": "HẠ TẦNG", "title": "TÊN TUYẾN", "headEnd": 5, "disclaimer": "Hướng tuyến minh hoạ theo quy hoạch công bố", "disclaimerFrom": 5 }, "camera": [ { "t": 0, "lng": 106.70, "lat": 10.78, "zoom": 10.5, "pitch": 20 }, { "t": 6, "zoom": 12, "pitch": 30 } ], "routes": [ { "id": "tuyen", "name": "Tên tuyến", "preset": "", "points": [], "kind": "planned", "infra": "metro", "flow": true, "dash": true, "start": 2 } ], "markers": [], "captions": [], "legends": [{ "auto": true, "start": 20, "end": 30 }] } ``` - Nền `satellite-soft` và `theme: "ba-vai"`: web tự tô màu theo vai, không ghi `color` từng mục. - Tuyến ghi `flow`, `dash`; tuyến quy hoạch có `kind: "planned"` nên disclaimer phải có chữ "minh hoạ". - Không ghi `titleStyle`, `titleColor`, `audio[]`: web tự bốc style, họ màu và tự thêm nhạc nền, tiếng hiệu ứng. ### Caption: câu có tiêu đề và câu thường ```json "captions": [ { "start": 7.8, "end": 11.2, "loai": "khoang-cach", "lead": "Metro dài khoảng", "hook": "45 KM", "extra": "với 31 nhà ga", "sub": "Tuyến metro dài khoảng 45 km với 31 nhà ga." }, { "start": 11.4, "end": 14.6, "sub": "Tuyến đi qua trung tâm rồi xuống khu Nam thành phố.", "highlight": ["khu Nam"] } ] ``` - Câu đầu có `hook`: web vẽ khối tiêu đề ba dòng (dẫn, nhấn, bổ sung) và không hiện `sub`. Mọi ý cần đọc nằm trong `lead`, `hook`, `extra`. - Câu sau không có `hook`: chỉ hiện phụ đề `sub`, `highlight` tô cụm chép đúng từng chữ trong `sub`. - `hook` in hoa, số viết bằng chữ số, đơn vị viết hoa. Câu 3 dòng nên dài từ 3,4 giây. ### Ghim dự án ```json "markers": [ { "id": "du-an", "kind": "pin", "lng": 106.7020, "lat": 10.7215, "label": "Tên dự án", "sub": "Phường, khu", "start": 3 } ] ``` - Toạ độ dự án do người dùng gửi. Tên dự án chỉ xuất hiện ở tag này, không lặp ở thẻ, tên tuyến, tên vùng. - Có ảnh vị trí thì thêm `images[]` với `"marker": "du-an"`. ### Vành đai cả vòng và khúc gần dự án ```json "routes": [ { "id": "vd3", "name": "Vành đai 3", "preset": "vanh-dai-3", "points": [], "flow": true, "dash": true, "start": 12 }, { "id": "vd3-gan", "name": "Khúc gần dự án", "of": "vd3", "from": 0.42, "to": 0.5, "kind": "highlight", "legend": false, "start": 15 } ] ``` - Lời đọc nhắc vành đai thì chạy hết tuyến bằng `preset`. Muốn nhấn khúc gần dự án thì thêm tuyến `of` cắt đoạn đó (`from`, `to` là phần 0 đến 1 dọc tuyến cha). ### Tiện ích kề dự án ```json "zones": [ { "id": "sieu-thi", "name": "Siêu thị GO!", "kind": "polygon", "points": [[106.7031, 10.7221], [106.7040, 10.7221], [106.7040, 10.7228], [106.7031, 10.7228]], "fillOpacity": 0.38, "width": 4, "glow": true, "start": 18, "end": 24 } ], "markers": [ { "id": "the-sieu-thi", "kind": "card", "target": "sieu-thi", "label": "Siêu thị GO!", "start": 18.3, "end": 24 } ] ``` - `points` của lô dán từ `zone` mà `find_lot` trả về, không tự vẽ. - Thẻ `card` có `target` là id lô: một dòng `label`, không `sub`, không ghi `lng`, `lat`. Thẻ hiện ít nhất 3,9 giây. ### Bay dọc tuyến metro ```json "routes": [ { "id": "m1", "name": "Metro số 1", "preset": "metro-1", "points": [], "infra": "metro", "flow": true, "dash": true } ], "tour": { "route": "m1", "from": "Bến Thành", "to": "Ba Son", "say": "Metro số 1 chạy từ Bến Thành tới Suối Tiên.", "stations": [ { "name": "Bến Thành", "note": "Trung tâm thành phố", "tags": ["Ngầm"], "say": "Ga Bến Thành nằm ngay trung tâm thành phố." } ] } ``` - Tên ga lấy từ `stations` của `list_library_routes`. Không viết `camera[]` dọc tuyến, không viết `captions[]` cho các câu `say`. - Chạy `validate_scene` rồi đặt `duration` theo giây kết thúc chuyến bay mà storyboard báo. ### File khác trong repo - `/sample-duyet-gd2.json`: file kiểm tra nét đường, màu sắc, không phải video kể chuyện, không dùng làm mẫu. ## Tiêu đề chữ (typo) trên khung dọc 9:16 Luật cho khối tiêu đề của `captions[]` (dẫn `lead`, nhấn `hook`, bổ sung `extra`) và phụ đề `sub`. Web tự vẽ, tự chọn style theo luật này; kịch bản chỉ cần viết đúng nội dung từng dòng. `validate_scene` báo khi kịch bản ghi tay `titleStyle` trái luật. ### Năm vùng từ trên xuống (khổ 9:16) | Vùng | Chiều cao | Dùng cho | |---|---|---| | 1 | 0 đến 8% | để trống (la bàn), cấm chữ | | 2 | 8% đến 30% | tiêu đề | | 3 | 30% đến 79% | bản đồ: ghim, tag, tuyến chính phải nằm ở đây | | 4 | 79% đến 87,5% | phụ đề cố định | | 5 | 87,5% đến 100% | để trống, cấm chữ | Ghim, tag rơi vào vùng 1 hoặc 5 là lỗi, vùng 2 hoặc 4 là cảnh báo. Sửa bằng camera (dời tâm, lùi zoom), không dời chữ, không ẩn tag. ### Ba dòng của một cảnh - Mỗi cảnh đúng một dòng nhấn (`hook`), in hoa, tối đa khoảng 12 ký tự. Dòng dẫn và dòng bổ sung viết thường. - Chọn dòng nhấn theo loại thông tin: | Loại | `lead` | `hook` | `extra` | |---|---|---|---| | Thời gian | Chỉ, Khoảng | 2 PHÚT | ra nút giao Liên Phường | | Khoảng cách | Cách | 3 KM | sân bay Tân Sơn Nhất | | Tỷ lệ, quy mô | Hơn, Gần | 70% | cây xanh, mặt nước | | Tên đường, khu | Mặt tiền, Nằm trong | VÕ CHÍ CÔNG | trục kết nối trung tâm | | Mốc tiến độ | Bàn giao | QUÝ 4 2026 | toàn bộ phân khu | | Giá | Chỉ từ | 600 TRIỆU | vốn tự có | - Câu có nhiều thứ: ưu tiên con số, rồi tên riêng, rồi tính từ. Số đứng cuối câu vẫn kéo lên làm nhấn ("Cách sân bay 8 km" thành Cách / 8 KM / sân bay). - Số viết bằng chữ số, đơn vị viết hoa trong dòng nhấn (PHÚT, KM, HA, %). - Không dùng dấu chấm giữa, gạch dài. Không số điện thoại, Zalo, web, QR. ### Bộ style đã duyệt 9 style: `M3` Chốt, `M6` Chốt đứng, `M7` Mặt trời, `M8` Chữ nền lớn, `M9` Bản tin, `M11` Thiệp, `M12` Số tầng, `M14` Hai cột, `M16` Dẫn đổi, nhấn đứng. Bỏ trống `titleStyle` thì web tự bốc; chỉ ghi tay khi thật cần, và phải theo luật: - Một họ màu cả clip: `titleColor` ở gốc kịch bản là một trong 12 họ: vang, cyan, kem-dao, vang-cam, dao-hong, xanh-duong, mint-la, champagne, hong-tim, bac-xanh, cam-do, hong-dao (`kem-dao` và 9 họ sau là dải dòng nhấn M16 tô cho mọi style). Thường bỏ trống: web tự bốc theo kịch bản, vàng gold 50 %, 50 % chia đều 11 họ còn lại (P77); chỉ ghi khi người dùng muốn một màu. - Nền sau tiêu đề sáng (bản đồ Đường phố sáng, trời trắng): ghi `nen: "sang"` ở gốc kịch bản hoặc ở caption đó; chữ có viền, bóng đậm, đọc được không cần phủ tối thêm. Nền thường thì không ghi. - Cả clip tối đa 3 style. - Mỗi caption có tiêu đề nên ghi `loai` (loại chi tiết): `thoi-gian`, `khoang-cach`, `quy-mo`, `gia`, `moc`, `ten`, `khac`. Không ghi thì web đoán theo `hook` (có tiền: giá; PHÚT, GIỜ: thời gian; KM: khoảng cách; QUÝ, NĂM: mốc; số khác: quy mô; không số: tên). Cảnh cùng loại mà khác ý thì thêm `nhom` (vd giá thuê `"thue"`, giá bán `"ban"`). - Không lặp một style hai cảnh liền nhau, trừ chuỗi cảnh có số cùng loại (cùng `nhom` nếu có) liền nhau (vd 3 cảnh thời gian giữ chung một style để so con số). Cảnh tên riêng, câu không số liền nhau vẫn phải khác style. - `M7`, `M8`, `M11`: tối đa 1 lần mỗi clip (M8: Phương 24/10/2026). `M7`, `M11` chỉ cho câu dài (`hook` từ 9 ký tự, hoặc `lead` + `extra` từ 22 ký tự). - `M9`: chỉ khi `hook` có 2 đến 3 chữ và từ 8 ký tự ("2 PHÚT", "70%" không dùng). - `M12`: chỉ cảnh giá (`loai: "gia"`) có `lead`, `hook` là số hoặc khoảng số + đơn vị tiền ("600 TRIỆU", "2,5 TỶ", "13-15 TRIỆU"); "10%" không dùng. - `M8`: cần chữ nền (`titleBg` của caption, `script.titleBg` hoặc `hud.tag`): tên dự án đầy đủ in hoa, đúng như tên gọi, không rút gọn, không cắt bớt chữ trong tên (tên dài thì chữ nền tự thu cho thấy trọn chữ); cảnh mở đầu ưu tiên M8. Tiêu đề M8 không nhắc lại tên dự án: chữ nền đã là tên nên dòng dẫn, nhấn, bổ sung của cảnh đó không chứa liền hai chữ của tên dự án (tên một chữ thì chữ đó); câu nhắc tên dự án thì dùng style khác. Ở Nexus Map, chữ nền là một phần cắt của tên ghim dự án (vd "RISE" cho "Solara Rise") thì `validate_scene` báo lỗi; caption ghi `titleStyle: "M8"` mà `lead`, `lead2`, `hook`, `extra` nhắc lại tên dự án (chữ nền hoặc tên ghim dự án) thì báo lỗi, câu mở đầu để web tự bốc mà nhắc lại tên thì cảnh báo. - `M16`: web chỉ bốc cho caption có `lead2` (dòng dẫn thứ hai, viết thường, cần `lead`) và caption có `lead2` chỉ lấy M16; web tự bốc, không cần ghi `titleStyle`. Muốn M16 cho caption một dòng dẫn thì ghi `titleStyle: "M16"` (dòng dẫn đứng yên, không đổi). Dòng dẫn `lead` đổi thành `lead2` lúc `doiLuc` (giây tính từ đầu caption, phải ghi; sau lúc dòng dẫn vào xong, trước lúc khối ra ít nhất 1 s), dòng nhấn đứng yên; vệt lóa trên dòng nhấn bật sẵn sau lúc đổi 0,5 s (`loe: false` để tắt). Họ màu nào M16 cũng vậy: dòng nhấn theo `mauNhan` của caption, một trong 10 dải (`kem-dao`, `vang-cam`, `dao-hong`, `xanh-duong`, `mint-la`, `champagne`, `hong-tim`, `bac-xanh`, `cam-do`, `hong-dao`); không ghi thì kem đào. Chọn dải nổi trên nền ngay sau dòng nhấn: nền sáng ấm (trời nắng, hồ bơi) chọn `cam-do`, trời xanh có cây `hong-dao`, nền tối `kem-dao`, nền nâu đỏ `mint-la`, tường vàng `xanh-duong`. - Style làm dòng nhấn phải thu cỡ quá 25% mới vừa khung thì web không dùng style đó cho câu ấy: rút gọn `hook`. ### Nhịp chữ - Vào 0,8 s, ra 0,5 s, dòng sau trễ 0,3 s; cảnh trước ra hết rồi cảnh sau mới vào. - Mỗi cảnh giữ đứng yên ít nhất 1 s (chữ trùng lời đọc) đến 1,5 s (chữ khác lời đọc). Câu đọc ngắn thì web co nhịp, rồi bỏ dòng bổ sung; vẫn thiếu thì gộp hai câu voice vào một cảnh chữ. - Cảnh 3 dòng nên dài từ 3,4 s, 2 dòng từ 2,2 s. - Vệt sáng lướt chữ màu chuyển: tắt mặc định. Bật (`loe: true`) cho cả clip hoặc riêng cảnh muốn gây chú ý; vệt lóe một lần, 0,7 s sau khi dòng vào, không cần chỉnh gì thêm. ### Tag trên bản đồ - Tag (nhãn ghim, điểm, tuyến) phải hiện liên tục ít nhất 3 s. - Tên ghim dự án 0 đến 6 chữ, chỉ tên dự án ("Imperia Sensa Park"); chi tiết (khu dân cư, mặt tiền đường) đưa vào caption. - Chữ, tag, ghim không bao giờ đè lên nhau. ### Riêng Nexus Map Phần trên lấy nguyên từ gói Nexus Typo (`lib/nexus-typo/luat-ai.md`, nguồn gốc luật chữ); đổi luật thì sửa ở Nexus Typo rồi chép gói mới. Phần này chỉ có ở Map: - Typo linh động, không ghi cứng: mỗi clip để web tự bốc họ màu và style. Map bốc vàng gold 30 % (không phải 50 % như dòng `titleColor` ở trên), 70 % chia đều 11 họ còn lại, theo nội dung kịch bản (cùng kịch bản ra cùng màu, kịch bản khác ra màu khác). Không chép `titleColor`, `titleStyle` từ mẫu sang clip mới; chỉ ghi khi người dùng chọn. `validate_scene` ghi chú (`notes`) khi kịch bản ghi cứng họ màu hoặc ghi tay style cho phần lớn caption. - Viền chữ phụ đề `sub`: `vienPhuDe` ở gốc kịch bản (cả clip) hoặc ở caption, mặc định xanh lá `#15803d`. Gợi ý lấy màu chữ, màu thương hiệu nổi bật của dự án; không dùng viền đen. - Phụ đề `sub` không hiện ở câu có `hook` và trong 3 giây đầu clip (từ giây 3 mờ hiện). Ý cần người xem đọc được trong câu có tiêu đề thì đưa vào `lead`, `hook`, `extra`. - Khổ 9:16: 3 giây đầu web tự gom tiêu đề (và nhãn tầng dưới) vào giữa khung (vùng TikTok không che), né ghim dự án, rồi trượt về chỗ thường. Câu mở đầu nên ngắn để cụm chữ không phải thu cỡ. - Nền bản đồ sáng (Sáng tối giản, Xám nhạt, Đường phố sáng, Đường phố, Địa hình, National Geographic): web tự bật nền sáng cho khối tiêu đề (chữ viền, bóng đậm), không cần ghi `nen`, không cần phủ tối thêm; nền khác không bật. Ghi `nen: "toi"` (cả clip hoặc caption) để tắt, `nen: "sang"` để bật trên nền khác (cảnh ảnh, video sáng). - `mauNhan` (M16): web không tự đo nền bản đồ, không ghi thì kem đào. Nền tối (Đêm đường vàng, Xanh kỹ thuật) giữ `kem-dao`; nền khác chọn theo cách chọn dải ở mục M16 phía trên, nhìn phần bản đồ ngay sau dòng nhấn (`preview_frames`). ## Danh sách tuyến có sẵn (thư viện ngày 2026-11-06) Ghi vào kịch bản `{ "id": "...", "name": "...", "preset": "", "points": [] }`. Web tự nạp hình dạng (và ga với tuyến metro) khi mở file. Tuyến ghi "quy hoạch, vẽ gần đúng" phải có `approx: true` và chữ "minh hoạ" trong `hud.disclaimer`. Tên tuyến dưới đây đã đổi gạch ngang vừa thành gạch nối thường, chép vào `name` được. | preset | Tên | Khu vực | km | Trạng thái | Số ga | |---|---|---|---|---|---| | `vanh-dai-2` | Vành đai 2 TP.HCM | TP.HCM | 64,8 | đang khai thác | | | `vanh-dai-3` | Vành đai 3 TP.HCM | TP.HCM | 128 | đang khai thác | | | `vanh-dai-4-hcm` | Vành đai 4 TP.HCM (đang thi công) | TP.HCM | 206 | đang thi công | | | `vanh-dai-1` | Vành đai 1 TP.HCM | TP.HCM | 26 | đang khai thác | | | `cao-toc-hcm-lt-dg` | Cao tốc TP.HCM - Long Thành - Dầu Giây | TP.HCM | 54,6 | | | | `cao-toc-hcm-trung-luong` | Cao tốc TP.HCM - Trung Lương | TP.HCM | 44,5 | | | | `cao-toc-ben-luc-long-thanh` | Cao tốc Bến Lức - Long Thành | TP.HCM | 55,9 | | | | `cao-toc-bien-hoa-vung-tau` | Cao tốc Biên Hòa - Vũng Tàu | TP.HCM | 53,7 | | | | `metro-1` | Metro số 1 Bến Thành - Suối Tiên | TP.HCM | 19,5 | | 14 | | `metro-2` | Metro số 2 Bến Thành - Tham Lương | TP.HCM | 17,5 | | 18 | | `metro-4` | Metro số 4 TP.HCM (quy hoạch, đoạn phía Nam) | TP.HCM | 19,6 | quy hoạch, vẽ gần đúng | 14 | | `metro-6` | Metro số 6 TP.HCM (quy hoạch) | TP.HCM | 23,8 | quy hoạch, vẽ gần đúng | 16 | | `ql1-hcm` | Quốc lộ 1 (đoạn qua TP.HCM) | TP.HCM | 180,4 | | | | `ql13` | Quốc lộ 13 | TP.HCM | 94,2 | | | | `ql22` | Quốc lộ 22 | TP.HCM | 59 | | | | `ql50` | Quốc lộ 50 | TP.HCM | 86,4 | | | | `ql51` | Quốc lộ 51 | TP.HCM | 65,4 | | | | `xa-lo-ha-noi` | Xa lộ Hà Nội | TP.HCM | 19,8 | | | | `vo-van-kiet` | Đại lộ Võ Văn Kiệt | TP.HCM | 16,9 | | | | `mai-chi-tho` | Đại lộ Mai Chí Thọ | TP.HCM | 7 | | | | `pham-van-dong` | Phạm Văn Đồng | TP.HCM | 12,2 | | | | `nguyen-van-linh` | Nguyễn Văn Linh | TP.HCM | 17,7 | | | | `vo-chi-cong` | Võ Chí Công | TP.HCM | 9,5 | | | | `vanh-dai-1-hn` | Vành đai 1 Hà Nội | Hà Nội | 9,8 | đang khai thác | | | `vanh-dai-2-hn` | Vành đai 2 Hà Nội | Hà Nội | 39,9 | đang khai thác | | | `vanh-dai-2-5-hn` | Vành đai 2,5 Hà Nội | Hà Nội | 19,6 | đang khai thác | | | `vanh-dai-3-hn` | Vành đai 3 Hà Nội | Hà Nội | 61 | đang khai thác | | | `vanh-dai-3-5-hn` | Vành đai 3,5 Hà Nội | Hà Nội | 21,9 | đang khai thác | | | `vanh-dai-4-hn` | Vành đai 4 Hà Nội (đang thi công) | Hà Nội | 85,5 | đang thi công | | | `metro-2a-hn` | Metro 2A Cát Linh - Hà Đông | Hà Nội | 13 | đang khai thác | 12 | | `metro-3-hn` | Metro số 3 Nhổn - ga Hà Nội | Hà Nội | 13,5 | đang khai thác | 12 | | `metro-2-hn` | Metro số 2 Hà Nội (đang thi công) | Hà Nội | 12 | đang thi công | | | `metro-5-hn` | Metro số 5 Văn Cao - Hòa Lạc (đang thi công) | Hà Nội | 39,7 | đang thi công | 20 | | `cao-toc-phap-van-cau-gie` | Cao tốc Pháp Vân - Cầu Giẽ | Hà Nội | 30,3 | đang khai thác | | | `cao-toc-ha-noi-hai-phong` | Cao tốc Hà Nội - Hải Phòng | Hà Nội | 101,2 | đang khai thác | | | `cao-toc-noi-bai-lao-cai` | Cao tốc Nội Bài - Lào Cai | Hà Nội | 170,8 | đang khai thác | | | `dai-lo-thang-long` | Đại lộ Thăng Long | Hà Nội | 28,9 | đang khai thác | | | `ql1-hn` | Quốc lộ 1 (đoạn qua Hà Nội) | Hà Nội | 173,3 | đang khai thác | | | `ql3` | Quốc lộ 3 (đoạn gần Hà Nội) | Hà Nội | 111,5 | đang khai thác | | | `ql5` | Quốc lộ 5 | Hà Nội | 116 | đang khai thác | | | `ql6` | Quốc lộ 6 (đoạn gần Hà Nội) | Hà Nội | 134,1 | đang khai thác | | | `ql32` | Quốc lộ 32 (đoạn gần Hà Nội) | Hà Nội | 116,7 | đang khai thác | | ## Danh sách vùng có sẵn (thư viện ngày 2026-11-01) Ranh giới hành chính thật từ OpenStreetMap, kể cả đơn vị đã giải thể (quận cũ trước 2021). Ghi vào `zones[]` `{ "id": "...", "name": "...", "preset": "", "points": [] }`. Web tự nạp ranh giới khi mở file. Tên vùng tự đứng ở tâm khối chính và tự né tên vùng khác; chỉ ghi `labelAt` khi muốn tên ở chỗ khác. | preset | Tên | Khu vực | km² | Nguồn | |---|---|---|---|---| | `quan-1-cu` | Quận 1 cũ | TP.HCM | 7,71 | OpenStreetMap relation 2587287, ranh giới ngày 01/06/2025 | | `quan-3-cu` | Quận 3 cũ | TP.HCM | 4,93 | OpenStreetMap relation 3819816, ranh giới ngày 01/06/2025 | | `quan-4-cu` | Quận 4 cũ | TP.HCM | 4,15 | OpenStreetMap relation 2778323, ranh giới ngày 01/06/2025 | | `quan-5-cu` | Quận 5 cũ | TP.HCM | 4,26 | OpenStreetMap relation 3820432, ranh giới ngày 01/06/2025 | | `quan-6-cu` | Quận 6 cũ | TP.HCM | 7,13 | OpenStreetMap relation 6228792, ranh giới ngày 01/06/2025 | | `quan-7-cu` | Quận 7 cũ | TP.HCM | 35,67 | OpenStreetMap relation 2764875, ranh giới ngày 01/06/2025 | | `quan-8-cu` | Quận 8 cũ | TP.HCM | 19,08 | OpenStreetMap relation 6888445, ranh giới ngày 01/06/2025 | | `quan-10-cu` | Quận 10 cũ | TP.HCM | 5,7 | OpenStreetMap relation 6228121, ranh giới ngày 01/06/2025 | | `quan-11-cu` | Quận 11 cũ | TP.HCM | 5,13 | OpenStreetMap relation 6846181, ranh giới ngày 01/06/2025 | | `quan-12-cu` | Quận 12 cũ | TP.HCM | 52,79 | OpenStreetMap relation 6923167, ranh giới ngày 01/06/2025 | | `quan-2-cu` | Quận 2 cũ | TP.HCM | 50,06 | OpenStreetMap relation 3799817, ranh giới ngày 01/12/2020 | | `quan-9-cu` | Quận 9 cũ | TP.HCM | 113,71 | OpenStreetMap relation 7144246, ranh giới ngày 01/12/2020 | | `quan-thu-duc-cu` | Quận Thủ Đức cũ | TP.HCM | 47,78 | OpenStreetMap relation 6941055, ranh giới ngày 01/12/2020 | | `tp-thu-duc-cu` | TP Thủ Đức cũ | TP.HCM | 211,33 | OpenStreetMap relation 11721235, ranh giới ngày 01/06/2025 | | `quan-binh-thanh-cu` | Quận Bình Thạnh cũ | TP.HCM | 20,77 | OpenStreetMap relation 3797166, ranh giới ngày 01/06/2025 | | `quan-binh-tan-cu` | Quận Bình Tân cũ | TP.HCM | 51,94 | OpenStreetMap relation 6909710, ranh giới ngày 01/06/2025 | | `quan-go-vap-cu` | Quận Gò Vấp cũ | TP.HCM | 19,73 | OpenStreetMap relation 6908316, ranh giới ngày 01/06/2025 | | `quan-phu-nhuan-cu` | Quận Phú Nhuận cũ | TP.HCM | 4,85 | OpenStreetMap relation 3851694, ranh giới ngày 01/06/2025 | | `quan-tan-binh-cu` | Quận Tân Bình cũ | TP.HCM | 22,4 | OpenStreetMap relation 6846177, ranh giới ngày 01/06/2025 | | `quan-tan-phu-cu` | Quận Tân Phú cũ | TP.HCM | 15,99 | OpenStreetMap relation 6846128, ranh giới ngày 01/06/2025 | | `huyen-binh-chanh-cu` | Huyện Bình Chánh cũ | TP.HCM | 252,19 | OpenStreetMap relation 7157268, ranh giới ngày 01/06/2025 | | `huyen-can-gio-cu` | Huyện Cần Giờ cũ | TP.HCM | 638,01 | OpenStreetMap relation 7157255, ranh giới ngày 01/06/2025 | | `huyen-cu-chi-cu` | Huyện Củ Chi cũ | TP.HCM | 434,44 | OpenStreetMap relation 7157220, ranh giới ngày 01/06/2025 | | `huyen-hoc-mon-cu` | Huyện Hóc Môn cũ | TP.HCM | 109,07 | OpenStreetMap relation 7157219, ranh giới ngày 01/06/2025 | | `huyen-nha-be-cu` | Huyện Nhà Bè cũ | TP.HCM | 99,87 | OpenStreetMap relation 7157197, ranh giới ngày 01/06/2025 | | `khu-dong` | Khu Đông | TP.HCM | 211,33 | OpenStreetMap relation 11721235, ranh giới ngày 01/06/2025 | | `khu-nam` | Khu Nam | TP.HCM | 135,57 | OpenStreetMap, gộp relation 2764875, 7157197, ranh giới ngày 01/06/2025 | | `khu-nam-rong` | Khu Nam (bản rộng) | TP.HCM | 1044,93 | OpenStreetMap, gộp relation 2764875, 7157197, 6888445, 7157268, 7157255, ranh giới ngày 01/06/2025 | | `khu-tay` | Khu Tây | TP.HCM | 80,2 | OpenStreetMap, gộp relation 6909710, 6846128, 6228792, 6846181, ranh giới ngày 01/06/2025 | | `khu-trung-tam` | Khu Trung tâm | TP.HCM | 12,64 | OpenStreetMap, gộp relation 2587287, 3819816, ranh giới ngày 01/06/2025 | | `khu-trung-tam-rong` | Khu Trung tâm (bản rộng) | TP.HCM | 52,37 | OpenStreetMap, gộp relation 2587287, 3819816, 2778323, 3820432, 6228121, 3851694, 3797166, ranh giới ngày 01/06/2025 | | `khu-bac` | Khu Bắc | TP.HCM | 616,06 | OpenStreetMap, gộp relation 6923167, 6908316, 7157219, 7157220, ranh giới ngày 01/06/2025 | | `khu-sai-gon` | Sài Gòn | TP.HCM | 7,71 | OpenStreetMap relation 2587287, ranh giới ngày 01/06/2025 | | `khu-cho-lon` | Chợ Lớn | TP.HCM | 4,26 | OpenStreetMap relation 3820432, ranh giới ngày 01/06/2025 | | `khu-cho-lon-rong` | Chợ Lớn | TP.HCM | 16,53 | OpenStreetMap, gộp relation 3820432, 6228792, 6846181, ranh giới ngày 01/06/2025 | | `tp-hcm` | TP.HCM | TP.HCM | 6691,24 | OpenStreetMap, gộp relation 2587287, 3819816, 2778323, 3820432, 6228792, 2764875, 6888445, 6228121, 6846181, 6923167, 11721235, 3797166, 6909710, 6908316, 3851694, 6846177, 6846128, 7157268, 7157255, 7157220, 7157219, 7157197, 7154449, 3871720, 7154352, 7154463, 7154447, 7155108, 7155122, 7154399, 7154470, 3607889, 3987528, 3610388, 7153137, 7153212, 3610389, 7153187, 3612628, ranh giới ngày 01/06/2024 | | `tp-hcm-cu` | TP.HCM cũ (trước 07/2025) | TP.HCM | 2026,7 | OpenStreetMap, gộp relation 2587287, 3819816, 2778323, 3820432, 6228792, 2764875, 6888445, 6228121, 6846181, 6923167, 11721235, 3797166, 6909710, 6908316, 3851694, 6846177, 6846128, 7157268, 7157255, 7157220, 7157219, 7157197, ranh giới ngày 01/06/2024 | | `dong-nai` | Đồng Nai | Đồng Nai | 12725,71 | OpenStreetMap relation 1904421 | | `dong-nai-cu` | Đồng Nai cũ (trước 07/2025) | Đồng Nai | 5854,2 | OpenStreetMap relation 1904421, ranh giới ngày 01/06/2025 | | `binh-duong-cu` | Bình Dương cũ | Bình Dương cũ | 2692,13 | OpenStreetMap relation 1906037, ranh giới ngày 01/06/2025 | | `ba-ria-vung-tau-cu` | Bà Rịa Vũng Tàu cũ | Bà Rịa Vũng Tàu cũ | 1968,48 | OpenStreetMap, gộp relation 3607889, 3987528, 3610388, 7153137, 7153212, 3610389, 7153187, 3612628, ranh giới ngày 01/06/2024 | | `thu-dau-mot-cu` | TP Thủ Dầu Một cũ | Bình Dương cũ | 118,27 | OpenStreetMap relation 7154449, ranh giới ngày 01/06/2025 | | `di-an-cu` | TP Dĩ An cũ | Bình Dương cũ | 59,9 | OpenStreetMap relation 3871720, ranh giới ngày 01/06/2025 | | `thuan-an-cu` | TP Thuận An cũ | Bình Dương cũ | 83,29 | OpenStreetMap relation 7154352, ranh giới ngày 01/06/2025 | | `tan-uyen-cu` | TP Tân Uyên cũ | Bình Dương cũ | 191,75 | OpenStreetMap relation 7154463, ranh giới ngày 01/06/2025 | | `ben-cat-cu` | TP Bến Cát cũ | Bình Dương cũ | 234,83 | OpenStreetMap relation 7154447, ranh giới ngày 01/06/2025 | | `bau-bang-cu` | Huyện Bàu Bàng cũ | Bình Dương cũ | 339,57 | OpenStreetMap relation 7155108, ranh giới ngày 01/06/2025 | | `bac-tan-uyen-cu` | Huyện Bắc Tân Uyên cũ | Bình Dương cũ | 400,22 | OpenStreetMap relation 7155122, ranh giới ngày 01/06/2025 | | `dau-tieng-cu` | Huyện Dầu Tiếng cũ | Bình Dương cũ | 719,02 | OpenStreetMap relation 7154399, ranh giới ngày 01/06/2025 | | `phu-giao-cu` | Huyện Phú Giáo cũ | Bình Dương cũ | 543,39 | OpenStreetMap relation 7154470, ranh giới ngày 01/06/2025 | | `vung-tau-cu` | TP Vũng Tàu cũ | Bà Rịa Vũng Tàu cũ | 137,1 | OpenStreetMap relation 3607889, ranh giới ngày 01/06/2025 | | `ba-ria-cu` | TP Bà Rịa cũ | Bà Rịa Vũng Tàu cũ | 91,82 | OpenStreetMap relation 3987528, ranh giới ngày 01/06/2025 | | `phu-my-cu` | TP Phú Mỹ cũ | Bà Rịa Vũng Tàu cũ | 328,93 | OpenStreetMap relation 3610388, ranh giới ngày 01/06/2025 | | `chau-duc-cu` | Huyện Châu Đức cũ | Bà Rịa Vũng Tàu cũ | 424,2 | OpenStreetMap relation 7153137, ranh giới ngày 01/06/2025 | | `xuyen-moc-cu` | Huyện Xuyên Mộc cũ | Bà Rịa Vũng Tàu cũ | 640,65 | OpenStreetMap relation 7153212, ranh giới ngày 01/06/2025 | | `long-dien-cu` | Huyện Long Điền cũ | Bà Rịa Vũng Tàu cũ | 78,46 | OpenStreetMap relation 3610389, ranh giới ngày 01/06/2024 | | `dat-do-cu` | Huyện Đất Đỏ cũ | Bà Rịa Vũng Tàu cũ | 189,67 | OpenStreetMap relation 7153187, ranh giới ngày 01/06/2024 | | `con-dao-cu` | Huyện Côn Đảo cũ | Bà Rịa Vũng Tàu cũ | 75,14 | OpenStreetMap relation 3612628, ranh giới ngày 01/06/2024 | | `bien-hoa-cu` | TP Biên Hòa cũ | Đồng Nai | 263,31 | OpenStreetMap relation 7154127, ranh giới ngày 01/06/2025 | | `long-thanh-cu` | Huyện Long Thành cũ | Đồng Nai | 430,42 | OpenStreetMap relation 7153928, ranh giới ngày 01/06/2025 | | `nhon-trach-cu` | Huyện Nhơn Trạch cũ | Đồng Nai | 377,01 | OpenStreetMap relation 7153857, ranh giới ngày 01/06/2025 | | `trang-bom-cu` | Huyện Trảng Bom cũ | Đồng Nai | 327,13 | OpenStreetMap relation 7154076, ranh giới ngày 01/06/2025 | | `long-khanh-cu` | TP Long Khánh cũ | Đồng Nai | 192,8 | OpenStreetMap relation 7153784, ranh giới ngày 01/06/2025 | | `phuong-an-dong` | Phường An Đông | TP.HCM | 1,33 | OpenStreetMap relation 19260682 | | `phuong-an-hoi-dong` | Phường An Hội Đông | TP.HCM | 3,28 | OpenStreetMap relation 19261095 | | `phuong-an-hoi-tay` | Phường An Hội Tây | TP.HCM | 3,81 | OpenStreetMap relation 19261097 | | `phuong-an-khanh` | Phường An Khánh | TP.HCM | 15,26 | OpenStreetMap relation 7351897 | | `phuong-an-lac` | Phường An Lạc | TP.HCM | 10,41 | OpenStreetMap relation 6915821 | | `phuong-an-nhon` | Phường An Nhơn | TP.HCM | 3,24 | OpenStreetMap relation 19261092 | | `phuong-an-phu` | Phường An Phú | TP.HCM | 16,74 | OpenStreetMap relation 13470504 | | `phuong-an-phu-dong` | Phường An Phú Đông | TP.HCM | 14,66 | OpenStreetMap relation 6941018 | | `phuong-ba-ria` | Phường Bà Rịa | TP.HCM | 15,57 | OpenStreetMap relation 4139667 | | `phuong-ban-co` | Phường Bàn Cờ | TP.HCM | 1 | OpenStreetMap relation 19260547 | | `phuong-bay-hien` | Phường Bảy Hiền | TP.HCM | 2,87 | OpenStreetMap relation 19261236 | | `phuong-ben-cat` | Phường Bến Cát | TP.HCM | 100,93 | OpenStreetMap relation 13477633 | | `phuong-ben-thanh` | Phường Bến Thành | TP.HCM | 1,86 | OpenStreetMap relation 19260503 | | `phuong-binh-co` | Phường Bình Cơ | TP.HCM | 73,41 | OpenStreetMap relation 13477544 | | `phuong-binh-dong` | Phường Bình Đông | TP.HCM | 8,87 | OpenStreetMap relation 19260927 | | `phuong-binh-duong` | Phường Bình Dương | TP.HCM | 57,66 | OpenStreetMap relation 13455518 | | `phuong-binh-hoa` | Phường Bình Hòa | TP.HCM | 18,43 | OpenStreetMap relation 13470503 | | `phuong-binh-hung-hoa` | Phường Bình Hưng Hòa | TP.HCM | 8,47 | OpenStreetMap relation 6915823 | | `phuong-binh-loi-trung` | Phường Bình Lợi Trung | TP.HCM | 3,9 | OpenStreetMap relation 19260953 | | `phuong-binh-phu` | Phường Bình Phú | TP.HCM | 2,85 | OpenStreetMap relation 19260733 | | `phuong-binh-quoi` | Phường Bình Quới | TP.HCM | 6,35 | OpenStreetMap relation 19260957 | | `phuong-binh-tan` | Phường Bình Tân | TP.HCM | 11,18 | OpenStreetMap relation 6915940 | | `phuong-binh-tay` | Phường Bình Tây | TP.HCM | 1,05 | OpenStreetMap relation 19260735 | | `phuong-binh-thanh` | Phường Bình Thạnh | TP.HCM | 3,32 | OpenStreetMap relation 19260954 | | `phuong-binh-thoi` | Phường Bình Thới | TP.HCM | 1,52 | OpenStreetMap relation 19260759 | | `phuong-binh-tien` | Phường Bình Tiên | TP.HCM | 1,62 | OpenStreetMap relation 19260736 | | `phuong-binh-tri-dong` | Phường Bình Trị Đông | TP.HCM | 7,15 | OpenStreetMap relation 6915941 | | `phuong-binh-trung` | Phường Bình Trưng | TP.HCM | 14,79 | OpenStreetMap relation 7364739 | | `phuong-cat-lai` | Phường Cát Lái | TP.HCM | 19,69 | OpenStreetMap relation 7370760 | | `phuong-cau-kieu` | Phường Cầu Kiệu | TP.HCM | 1,24 | OpenStreetMap relation 19261675 | | `phuong-cau-ong-lanh` | Phường Cầu Ông Lãnh | TP.HCM | 1,59 | OpenStreetMap relation 19260502 | | `phuong-chanh-hiep` | Phường Chánh Hiệp | TP.HCM | 19,92 | OpenStreetMap relation 10590955 | | `phuong-chanh-hung` | Phường Chánh Hưng | TP.HCM | 4,66 | OpenStreetMap relation 19260925 | | `phuong-chanh-phu-hoa` | Phường Chánh Phú Hòa | TP.HCM | 69,39 | OpenStreetMap relation 13477632 | | `phuong-cho-lon` | Phường Chợ Lớn | TP.HCM | 1,67 | OpenStreetMap relation 19260681 | | `phuong-cho-quan` | Phường Chợ Quán | TP.HCM | 1,28 | OpenStreetMap relation 19260683 | | `phuong-di-an` | Phường Dĩ An | TP.HCM | 21,29 | OpenStreetMap relation 8448992 | | `phuong-dien-hong` | Phường Diên Hồng | TP.HCM | 1,84 | OpenStreetMap relation 19260771 | | `phuong-dong-hoa` | Phường Đông Hòa | TP.HCM | 21,87 | OpenStreetMap relation 3870770 | | `phuong-dong-hung-thuan` | Phường Đông Hưng Thuận | TP.HCM | 8,26 | OpenStreetMap relation 6928153 | | `phuong-duc-nhuan` | Phường Đức Nhuận | TP.HCM | 2,14 | OpenStreetMap relation 19261676 | | `phuong-gia-dinh` | Phường Gia Định | TP.HCM | 2,76 | OpenStreetMap relation 19260955 | | `phuong-go-vap` | Phường Gò Vấp | TP.HCM | 2,82 | OpenStreetMap relation 19261094 | | `phuong-hanh-thong` | Phường Hạnh Thông | TP.HCM | 3,37 | OpenStreetMap relation 19261093 | | `phuong-hiep-binh` | Phường Hiệp Bình | TP.HCM | 15,96 | OpenStreetMap relation 7138137 | | `phuong-hoa-binh` | Phường Hòa Bình | TP.HCM | 0,98 | OpenStreetMap relation 19260760 | | `phuong-hoa-hung` | Phường Hòa Hưng | TP.HCM | 2,59 | OpenStreetMap relation 19260769 | | `phuong-hoa-loi` | Phường Hòa Lợi | TP.HCM | 34,05 | OpenStreetMap relation 13477612 | | `phuong-khanh-hoi` | Phường Khánh Hội | TP.HCM | 1,05 | OpenStreetMap relation 19260589 | | `phuong-lai-thieu` | Phường Lái Thiêu | TP.HCM | 15,23 | OpenStreetMap relation 13470501 | | `phuong-linh-xuan` | Phường Linh Xuân | TP.HCM | 12,28 | OpenStreetMap relation 8427050 | | `phuong-long-binh` | Phường Long Bình | TP.HCM | 26,49 | OpenStreetMap relation 7342307 | | `phuong-long-huong` | Phường Long Hương | TP.HCM | 41,55 | OpenStreetMap relation 4132582 | | `phuong-long-nguyen` | Phường Long Nguyên | TP.HCM | 107,9 | OpenStreetMap relation 15044270 | | `phuong-long-phuoc` | Phường Long Phước | TP.HCM | 34,15 | OpenStreetMap relation 7342308 | | `phuong-long-truong` | Phường Long Trường | TP.HCM | 24,45 | OpenStreetMap relation 7342511 | | `phuong-minh-phung` | Phường Minh Phụng | TP.HCM | 1,27 | OpenStreetMap relation 19260758 | | `phuong-nhieu-loc` | Phường Nhiêu Lộc | TP.HCM | 1,71 | OpenStreetMap relation 19260545 | | `phuong-phu-an` | Phường Phú An | TP.HCM | 35,07 | OpenStreetMap relation 13477595 | | `phuong-phu-dinh` | Phường Phú Định | TP.HCM | 5,79 | OpenStreetMap relation 19260926 | | `phuong-phu-lam` | Phường Phú Lâm | TP.HCM | 2 | OpenStreetMap relation 19260734 | | `phuong-phu-loi` | Phường Phú Lợi | TP.HCM | 18,01 | OpenStreetMap relation 13455517 | | `phuong-phu-my` | Phường Phú Mỹ | TP.HCM | 69,57 | OpenStreetMap relation 5485644 | | `phuong-phu-nhuan` | Phường Phú Nhuận | TP.HCM | 1,45 | OpenStreetMap relation 19261674 | | `phuong-phu-thanh` | Phường Phú Thạnh | TP.HCM | 3,02 | OpenStreetMap relation 6890889 | | `phuong-phu-tho` | Phường Phú Thọ | TP.HCM | 1,36 | OpenStreetMap relation 19260761 | | `phuong-phu-tho-hoa` | Phường Phú Thọ Hòa | TP.HCM | 3 | OpenStreetMap relation 6890890 | | `phuong-phu-thuan` | Phường Phú Thuận | TP.HCM | 10,3 | OpenStreetMap relation 2766949 | | `phuong-phuoc-long` | Phường Phước Long | TP.HCM | 9,23 | OpenStreetMap relation 7342567 | | `phuong-phuoc-thang` | Phường Phước Thắng | TP.HCM | 46,25 | OpenStreetMap relation 3610170 | | `phuong-rach-dua` | Phường Rạch Dừa | TP.HCM | 12,18 | OpenStreetMap relation 3610160 | | `phuong-sai-gon` | Phường Sài Gòn | TP.HCM | 3,02 | OpenStreetMap relation 19260504 | | `phuong-tam-binh` | Phường Tam Bình | TP.HCM | 10,72 | OpenStreetMap relation 7144243 | | `phuong-tam-long` | Phường Tam Long | TP.HCM | 34,69 | OpenStreetMap relation 4137054 | | `phuong-tam-thang` | Phường Tam Thắng | TP.HCM | 11,46 | OpenStreetMap relation 3616747 | | `phuong-tan-binh` | Phường Tân Bình | TP.HCM | 2,2 | OpenStreetMap relation 19261237 | | `phuong-tan-dinh` | Phường Tân Định | TP.HCM | 1,23 | OpenStreetMap relation 19260505 | | `phuong-tan-dong-hiep` | Phường Tân Đông Hiệp | TP.HCM | 21,35 | OpenStreetMap relation 13420411 | | `phuong-tan-hai` | Phường Tân Hải | TP.HCM | 51,78 | OpenStreetMap relation 8051120 | | `phuong-tan-hiep` | Phường Tân Hiệp | TP.HCM | 46,85 | OpenStreetMap relation 13477545 | | `phuong-tan-hoa` | Phường Tân Hòa | TP.HCM | 1,48 | OpenStreetMap relation 19261233 | | `phuong-tan-hung` | Phường Tân Hưng | TP.HCM | 8,52 | OpenStreetMap relation 2766950 | | `phuong-tan-khanh` | Phường Tân Khánh | TP.HCM | 38,39 | OpenStreetMap relation 13477540 | | `phuong-tan-my` | Phường Tân Mỹ | TP.HCM | 6,5 | OpenStreetMap relation 2766953 | | `phuong-tan-phu` | Phường Tân Phú | TP.HCM | 2,48 | OpenStreetMap relation 6890891 | | `phuong-tan-phuoc` | Phường Tân Phước | TP.HCM | 79,93 | OpenStreetMap relation 5485645 | | `phuong-tan-son` | Phường Tân Sơn | TP.HCM | 10,06 | OpenStreetMap relation 19261238 | | `phuong-tan-son-hoa` | Phường Tân Sơn Hòa | TP.HCM | 2,64 | OpenStreetMap relation 19261234 | | `phuong-tan-son-nhat` | Phường Tân Sơn Nhất | TP.HCM | 3,19 | OpenStreetMap relation 19261235 | | `phuong-tan-son-nhi` | Phường Tân Sơn Nhì | TP.HCM | 3,5 | OpenStreetMap relation 6892359 | | `phuong-tan-tao` | Phường Tân Tạo | TP.HCM | 14,79 | OpenStreetMap relation 6915944 | | `phuong-tan-thanh` | Phường Tân Thành | TP.HCM | 61,55 | OpenStreetMap relation 8081287 | | `phuong-tan-thoi-hiep` | Phường Tân Thới Hiệp | TP.HCM | 8,03 | OpenStreetMap relation 6928155 | | `phuong-tan-thuan` | Phường Tân Thuận | TP.HCM | 10,23 | OpenStreetMap relation 2766956 | | `phuong-tan-uyen` | Phường Tân Uyên | TP.HCM | 93,05 | OpenStreetMap relation 13477425 | | `phuong-tang-nhon-phu` | Phường Tăng Nhơn Phú | TP.HCM | 19,59 | OpenStreetMap relation 7343271 | | `phuong-tay-nam` | Phường Tây Nam | TP.HCM | 114,61 | OpenStreetMap relation 13477596 | | `phuong-tay-thanh` | Phường Tây Thạnh | TP.HCM | 3,95 | OpenStreetMap relation 6892362 | | `phuong-thanh-my-tay` | Phường Thạnh Mỹ Tây | TP.HCM | 4,44 | OpenStreetMap relation 19260956 | | `phuong-thoi-an` | Phường Thới An | TP.HCM | 14,83 | OpenStreetMap relation 6941014 | | `phuong-thoi-hoa` | Phường Thới Hòa | TP.HCM | 37,94 | OpenStreetMap relation 13477634 | | `phuong-thong-tay-hoi` | Phường Thông Tây Hội | TP.HCM | 3,23 | OpenStreetMap relation 19261096 | | `phuong-thu-dau-mot` | Phường Thủ Dầu Một | TP.HCM | 15,56 | OpenStreetMap relation 8448188 | | `phuong-thu-duc` | Phường Thủ Đức | TP.HCM | 8,75 | OpenStreetMap relation 7138136 | | `phuong-thuan-an` | Phường Thuận An | TP.HCM | 16,1 | OpenStreetMap relation 13470588 | | `phuong-thuan-giao` | Phường Thuận Giao | TP.HCM | 16,83 | OpenStreetMap relation 13470506 | | `phuong-trung-my-tay` | Phường Trung Mỹ Tây | TP.HCM | 6,92 | OpenStreetMap relation 6928030 | | `phuong-vinh-hoi` | Phường Vĩnh Hội | TP.HCM | 1,18 | OpenStreetMap relation 19260590 | | `phuong-vinh-tan` | Phường Vĩnh Tân | TP.HCM | 61,45 | OpenStreetMap relation 13477543 | | `phuong-vung-tau` | Phường Vũng Tàu | TP.HCM | 14,84 | OpenStreetMap relation 3610162 | | `phuong-vuon-lai` | Phường Vườn Lài | TP.HCM | 1,28 | OpenStreetMap relation 19260770 | | `phuong-xom-chieu` | Phường Xóm Chiếu | TP.HCM | 1,92 | OpenStreetMap relation 19260588 | | `phuong-xuan-hoa` | Phường Xuân Hòa | TP.HCM | 2,22 | OpenStreetMap relation 19260546 | | `xa-an-long` | Xã An Long | TP.HCM | 99,24 | OpenStreetMap relation 15350010 | | `xa-an-nhon-tay` | Xã An Nhơn Tây | TP.HCM | 77,49 | OpenStreetMap relation 7621976 | | `xa-an-thoi-dong` | Xã An Thới Đông | TP.HCM | 238,26 | OpenStreetMap relation 7468178 | | `xa-ba-diem` | Xã Bà Điểm | TP.HCM | 27,3 | OpenStreetMap relation 7638094 | | `xa-bac-tan-uyen` | Xã Bắc Tân Uyên | TP.HCM | 143,57 | OpenStreetMap relation 15071230 | | `xa-bau-bang` | Xã Bàu Bàng | TP.HCM | 84,07 | OpenStreetMap relation 15044266 | | `xa-bau-lam` | Xã Bàu Lâm | TP.HCM | 124,46 | OpenStreetMap relation 10329654 | | `xa-binh-chanh` | Xã Bình Chánh | TP.HCM | 21,35 | OpenStreetMap relation 7462674 | | `xa-binh-chau` | Xã Bình Châu | TP.HCM | 85,62 | OpenStreetMap relation 11379195 | | `xa-binh-gia` | Xã Bình Giã | TP.HCM | 66,75 | OpenStreetMap relation 8145048 | | `xa-binh-hung` | Xã Bình Hưng | TP.HCM | 32,63 | OpenStreetMap relation 7462675 | | `xa-binh-khanh` | Xã Bình Khánh | TP.HCM | 158,62 | OpenStreetMap relation 7468179 | | `xa-binh-loi` | Xã Bình Lợi | TP.HCM | 54,09 | OpenStreetMap relation 7462676 | | `xa-binh-my` | Xã Bình Mỹ | TP.HCM | 54,51 | OpenStreetMap relation 7621978 | | `xa-can-gio` | Xã Cần Giờ | TP.HCM | 162,54 | OpenStreetMap relation 7468177 | | `xa-chau-duc` | Xã Châu Đức | TP.HCM | 84,73 | OpenStreetMap relation 8162714 | | `xa-chau-pha` | Xã Châu Pha | TP.HCM | 66,14 | OpenStreetMap relation 8051119 | | `xa-cu-chi` | Xã Củ Chi | TP.HCM | 64,79 | OpenStreetMap relation 7629287 | | `xa-dat-do` | Xã Đất Đỏ | TP.HCM | 120,57 | OpenStreetMap relation 6190340 | | `xa-dau-tieng` | Xã Dầu Tiếng | TP.HCM | 183,12 | OpenStreetMap relation 15328440 | | `xa-dong-thanh` | Xã Đông Thạnh | TP.HCM | 30,24 | OpenStreetMap relation 7638095 | | `xa-hiep-phuoc` | Xã Hiệp Phước | TP.HCM | 63,39 | OpenStreetMap relation 7650793 | | `xa-ho-tram` | Xã Hồ Tràm | TP.HCM | 92,76 | OpenStreetMap relation 8165499 | | `xa-hoa-hiep` | Xã Hòa Hiệp | TP.HCM | 98,95 | OpenStreetMap relation 11379196 | | `xa-hoa-hoi` | Xã Hòa Hội | TP.HCM | 135,48 | OpenStreetMap relation 10330034 | | `xa-hoc-mon` | Xã Hóc Môn | TP.HCM | 16,45 | OpenStreetMap relation 7638093 | | `xa-hung-long` | Xã Hưng Long | TP.HCM | 35,54 | OpenStreetMap relation 7462678 | | `xa-kim-long` | Xã Kim Long | TP.HCM | 64,01 | OpenStreetMap relation 8121764 | | `xa-long-dien` | Xã Long Điền | TP.HCM | 51,37 | OpenStreetMap relation 3610394 | | `xa-long-hai` | Xã Long Hải | TP.HCM | 27,09 | OpenStreetMap relation 5485503 | | `xa-long-hoa` | Xã Long Hòa | TP.HCM | 161,09 | OpenStreetMap relation 15328437 | | `xa-long-son` | Xã Long Sơn | TP.HCM | 51,75 | OpenStreetMap relation 3610360 | | `xa-minh-thanh` | Xã Minh Thạnh | TP.HCM | 164,03 | OpenStreetMap relation 15328433 | | `xa-ngai-giao` | Xã Ngãi Giao | TP.HCM | 69,34 | OpenStreetMap relation 8115640 | | `xa-nghia-thanh` | Xã Nghĩa Thành | TP.HCM | 65,27 | OpenStreetMap relation 8077536 | | `xa-nha-be` | Xã Nhà Bè | TP.HCM | 37,28 | OpenStreetMap relation 7650792 | | `xa-nhuan-duc` | Xã Nhuận Đức | TP.HCM | 61,97 | OpenStreetMap relation 7627377 | | `xa-phu-giao` | Xã Phú Giáo | TP.HCM | 197,71 | OpenStreetMap relation 15350067 | | `xa-phu-hoa-dong` | Xã Phú Hòa Đông | TP.HCM | 59,75 | OpenStreetMap relation 7627379 | | `xa-phuoc-hai` | Xã Phước Hải | TP.HCM | 69,14 | OpenStreetMap relation 7867844 | | `xa-phuoc-hoa` | Xã Phước Hòa | TP.HCM | 122,8 | OpenStreetMap relation 15350008 | | `xa-phuoc-thanh` | Xã Phước Thành | TP.HCM | 123,62 | OpenStreetMap relation 15350042 | | `xa-tan-an-hoi` | Xã Tân An Hội | TP.HCM | 53,43 | OpenStreetMap relation 7629221 | | `xa-tan-nhut` | Xã Tân Nhựt | TP.HCM | 43,64 | OpenStreetMap relation 7463544 | | `xa-tan-vinh-loc` | Xã Tân Vĩnh Lộc | TP.HCM | 33,95 | OpenStreetMap relation 7463547 | | `xa-thai-my` | Xã Thái Mỹ | TP.HCM | 62,23 | OpenStreetMap relation 7629288 | | `xa-thanh-an-can-gio` | Xã Thạnh An | TP.HCM | 106,62 | OpenStreetMap relation 7468247 | | `xa-thanh-an-dau-tieng` | Xã Thanh An | TP.HCM | 140 | OpenStreetMap relation 15328441 | | `xa-thuong-tan` | Xã Thường Tân | TP.HCM | 122,61 | OpenStreetMap relation 15071235 | | `xa-tru-van-tho` | Xã Trừ Văn Thố | TP.HCM | 76,5 | OpenStreetMap relation 15044265 | | `xa-vinh-loc` | Xã Vĩnh Lộc | TP.HCM | 30,52 | OpenStreetMap relation 7463546 | | `xa-xuan-son` | Xã Xuân Sơn | TP.HCM | 74,23 | OpenStreetMap relation 8165423 | | `xa-xuan-thoi-son` | Xã Xuân Thới Sơn | TP.HCM | 35,07 | OpenStreetMap relation 7638253 | | `xa-xuyen-moc` | Xã Xuyên Mộc | TP.HCM | 103,21 | OpenStreetMap relation 8385623 | | `dac-khu-con-dao` | Đặc khu Côn Đảo | TP.HCM | 74,7 | OpenStreetMap relation 3612628 |