## ChronoLocus User Guide (使用指南)

### What ChronoLocus Does

ChronoLocus batch-renames photos and videos based on capture time, so your media library stays tidy and searchable.

Key ideas:

- Names are built from capture time + a per-day index (01, 02, 03…).
- Panorama photos may get a `___PANO` marker.
- Videos may include duration as `___HHMMSS` when available.
- Live Photos may get a `___LIVE` marker, and the photo + `.MOV` share the same per-day index.
- Advanced edition can blend folder name info (Location / Event) into the filename.

---

### Quick Start (Recommended)

1) Select your input
- Select Folder: scans all subfolders
- Select Files: uses only the files you pick

2) Preview
- Click Preview to see `original → new` before any rename happens.

3) Rename
- Click Start Rename only after the preview looks correct.

4) Confirm / Undo
- After renaming, you can confirm the result.
- You can undo the last rename (if Undo is available in your edition) until you select new input or close the app.

---

### File Naming Format

Basic format:

```
YYYY-MM-DD___INDEX___HH.MM.SS__ORIGINAL.ext
```

About `ORIGINAL` (Original token):

- `ORIGINAL` is a compact identifier extracted from the source filename (for example `IMG_E1234`, `VID_0001`, `PXL_20240628_082231`, `DJI_0420`).
- It is always kept at the end of the renamed filename for traceability, so you can quickly map a renamed file back to its source.
- If ChronoLocus cannot recognize a known camera/phone pattern, it falls back to a sanitized version of the original filename stem (characters outside `[a-zA-Z0-9_中文-]` are removed; spaces become `-`).
- If a file has already been renamed by ChronoLocus, ChronoLocus can recover `ORIGINAL` from the trailing `__ORIGINAL.ext` part to keep reruns stable.

Examples:

- `IMG_1234.HEIC` → `ORIGINAL = IMG_1234`
- `IMG_E1234.HEIC` → `ORIGINAL = IMG_E1234` (common iPhone edited/export variant)
- `PXL_20240628_082231123.jpg` → `ORIGINAL = PXL_20240628_082231`
- `DJI_0420.MP4` → `ORIGINAL = DJI_0420`
- `WeChat_2020-06-28_082231.jpg` → `ORIGINAL = WeChat_2020-06-28_082231` (fallback)

Examples:

- Basic:
  - `2001-06-28___001___08.22.31__IMG_1001.HEIC`
- Advanced (Folder name in filename enabled):
  - `2001-06-28___Paris___001___Eiffel_Tower___08.22.31__IMG_1001.HEIC`

Optional parts:

- Panorama marker: `___PANO`
- Video duration: `___HHMMSS`
- Live Photo marker: `___LIVE` (when a photo + a paired `.MOV` are detected as a single Live Photo)

Live Photos:

- When ChronoLocus detects a Live Photo pair (photo + `.MOV`) with the same `ORIGINAL` token in the same folder, both files share the same per-day `INDEX` so they stay paired in Explorer.

Missing capture time (folder-date fallback):

- If some files in a `YYYYMMDD___<name>` folder have missing capture-time metadata, ChronoLocus can fall back to the folder date for those files.
- In a mixed day (real capture time + fallback), ChronoLocus assigns indices to real files first (1..N), then assigns fallback files at the end of the day starting from the next 100-block (for example 210 → 300). If the index would exceed the day limit (e.g. 999 for 3 digits), it continues from N+1.
- If you see skipped files due to missing capture time, ChronoLocus may suggest renaming a `YYYYMMDD_<name>` folder to `YYYYMMDD___<name>` to enable folder-date fallback.

---

### Folder Naming Patterns (Advanced: Folder Name in Filename)

If you want Location / Event embedded into filenames, name your folders using one of these patterns:

- `Paris` → Event/Location
- `Paris___Eiffel_Tower` → Event/Location + Moment
- `20010628_Paris` → Date indication prefix + Event/Location (the `YYYYMMDD_` part is ignored during parsing; it only helps you sort files into date folders)

Notes:

- If folder names don’t match the patterns, the folder field may be empty or simplified, but capture-time rules still apply.
- You can also use “Project” instead of “Event/Location” if it fits your workflow.

---

### Supported Media Formats & Devices

ChronoLocus detects supported media by file extension.

Supported photo formats:

- `.jpg`, `.jpeg`
- `.heic`, `.heif`
- `.png`, `.gif`
- `.bmp`
- `.tiff`, `.tif`

Supported video formats:

- `.mov`, `.mp4`
- `.avi`, `.mkv`
- `.mpg`, `.mpeg`
- `.webm`

Common supported sources (devices/apps):

- iPhone / iPad (Photos, Live Photos)
- Android phones (including Google Pixel)
- Digital cameras (Canon / Nikon / Sony / Fuji)
- Action / drone cameras (GoPro / DJI)

Notes:

- Some files may still be skipped if capture-time metadata cannot be read.
- Folder-date fallback works only when the folder name starts with `YYYYMMDD___`.

---

### Safety Tips

- Renaming changes file paths and may affect photo libraries, editing projects, or sync tools.
- Test on copies or make a backup before running large batches.
- During processing, don’t move/delete files; close apps that may lock media files (players, editors, etc.).

---

### Licensing & Editions

Open `Help → License Information` to check:

- Your current edition (Effective)
- Your verified license status (Source)
- Feature comparison (Edition Comparison)

If your edition doesn’t look correct:

- Ensure you’re using the same Windows user account each time.
- If you’re offline, try connecting once so the app can verify your license again.

---

### Troubleshooting

**ExifTool not found**

- ChronoLocus requires ExifTool to read capture time from media files.
- In the official Windows ZIP release, ExifTool is shipped inside the `exiftool\` folder next to `ChronoLocus.exe` (no extra install required).
- Note: For the common Windows ExifTool package, `exiftool\exiftool.exe` also needs `exiftool\exiftool_files\` to run.
- If you downloaded a build without ExifTool bundled, install ExifTool and ensure it is available on PATH, or set `EXIFTOOL_PATH` / `RENAME_MEDIA_EXIFTOOL_PATH` to its location.

**Windows ZIP: optional auto-setup for ExifTool**

- If you want a “one-click” setup (recommended for non-technical users), run:
  - `Setup_ExifTool_PATH.bat` (in the same folder as `ChronoLocus.exe`)
- What it does:
  - Sets `EXIFTOOL_PATH` and `RENAME_MEDIA_EXIFTOOL_PATH` to `<app folder>\exiftool\exiftool.exe`
  - Adds `<app folder>\exiftool\` to your user PATH (so ExifTool can be found by other tools too)
- After running it, restart Command Prompt / PowerShell (or sign out/in) for the PATH change to take effect.
- If you already have ExifTool installed and working system-wide, you can skip this step.

---

### Build / Packaging (for developers)

To build a downloadable Windows ZIP (with ExifTool bundled):

```powershell
cd d:\MyDoc\MyDev\MyProjects\Chronova\app\dev_path03
.\chronolocus_pack_release.ps1 -ExeName ChronoLocus -ExifToolZip .\exiftool\exiftool-13.55_64.zip
```

**Supported media formats**

- ChronoLocus detects supported media by file extension.
- Open `Help → Supported Media Formats` to see the current list (photos/videos) for your build.
- Common sources include iPhone/iPad, Android phones (including Google Pixel), Canon/Nikon/Sony/Fuji cameras, and GoPro/DJI devices.

**Preview looks wrong**

- Check folder naming patterns (Advanced feature).
- Try adjusting capture-time assumptions by re-running Preview.
- If some files have missing metadata, they may fall back to a simplified result.
