From 8d2d422c6c21f87dc4f9edb4037f14a306913065 Mon Sep 17 00:00:00 2001
From: hbrain <hbrain@piagent.local>
Date: Mon, 25 May 2026 18:52:36 +0000
Subject: [PATCH] Require key-value data file syntax

---
 README.md   | 34 ++++++++++++++--------------------
 movmaker.py |  6 ++++--
 2 files changed, 18 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 6d391bb..1a050b9 100644
--- a/README.md
+++ b/README.md
@@ -107,39 +107,33 @@ Files are ordered by filename, so names like this work well:
 
 ## data.txt
 
-`data.txt` is optional.
+`data.txt` is optional, but if present every non-empty, non-comment line must use mandatory `key: value` syntax. Plain positional lines are not supported.
 
-Simplest format:
+Movie metadata keys:
 
 ```text
-Paris Trip
-Paris, France
-May 2024
+Title: Paris Trip
+Location: Paris, France
+Date: May 2024
+Description: Longer description shown in MVLog and embedded in final MP4 metadata.
 ```
 
-Those three lines mean:
+Supported metadata key aliases:
 
-1. title
-2. location
-3. date
+- title: `Title` or `Name`
+- location: `Location`, `Place`, or `Where`
+- date: `Date`, `Dates`, or `When`
+- description: `Description`, `Desc`, or `Synopsis`
 
-If the date line is omitted, movmaker uses the date from the first picture/video and displays it like:
+If the date entry is omitted, movmaker uses the date from the first picture/video and displays it like:
 
 ```text
 May 2026
 ```
 
-If the location line is omitted and GPS coordinates are found in the first picture/video that has them, movmaker reverse geocodes them and uses that as the location. It tries to return only `city/town/village, country`; if no city/town/village is found, it uses just the country.
+If the location entry is omitted and GPS coordinates are found in the first picture/video that has them, movmaker reverse geocodes them and uses that as the location. It tries to return only `city/town/village, country`; if no city/town/village is found, it uses just the country.
 
-Key/value format also works:
-
-```text
-title: Paris Trip
-date: May 2024
-place: Paris, France
-```
-
-Optional per-file captions are supported:
+Any other `key: value` line is treated as a per-file caption where the key is the exact media filename:
 
 ```text
 IMG_001.jpg: Eiffel Tower
diff --git a/movmaker.py b/movmaker.py
index 4c8f029..fbdf4ed 100755
--- a/movmaker.py
+++ b/movmaker.py
@@ -523,10 +523,12 @@ def parse_data_file(path: Path | None) -> MovieData:
         return MovieData(captions={})
 
     data = MovieData(captions={})
-    for raw in path.read_text(encoding="utf-8", errors="replace").splitlines():
+    for line_no, raw in enumerate(path.read_text(encoding="utf-8", errors="replace").splitlines(), start=1):
         line = raw.strip()
-        if not line or line.startswith("#") or ":" not in line:
+        if not line or line.startswith("#"):
             continue
+        if ":" not in line:
+            raise SystemExit(f"Invalid data file syntax in {path} line {line_no}: every entry must be key: value")
         key, value = line.split(":", 1)
         key = key.strip()
         value = value.strip()