gedcom-ts 2026.5.4 → 2026.6.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes of gedcom-ts
 
+## [2026.6.0] - 2026-06-01
+
+### Added
+
+- **Multimédia GEDCOM 7 (`OBJE`)** : import et export complets des enregistrements `0 @O…@ OBJE` avec plusieurs `FILE`, `FORM`, `MEDI` (`AUDIO`, `PHOTO`, `VIDEO`, …), `PHRASE`, `TITL` et variantes `FILE`.`TRAN` (transcodage, WebVTT).
+- **`ReadGed.objeRecordsById`** : map des OBJE absorbés depuis le fichier (round-trip via `GedcomExportOptions.objeRecordsById`).
+- **Types et utilitaires OBJE** : `ObjeRecord`, `ObjeFileEntry`, `primaryObjeFileUri`, `parseStandaloneObjeBlock`, `formatObjeRecordBlock`, `guessMediFromForm`, `registerObjeRecord`.
+- **Entretiens audio / histoire orale** : actes `EVEN` + `TYPE Interview` (ou « Oral history ») avec lien `2 OBJE`, note de transcription (`2 NOTE`) et API dédiée — `createAudioInterviewAct`, `attachAudioInterviewToAct`, `editAct(act).asAudioInterview()`, `editAudioInterviewAct`.
+- **Détection et lecture** : `isAudioInterviewAct`, `isAudioInterviewEvenType`, `getAudioInterviewTranscription`, `getAudioInterviewMedia`, `getAudioInterviewObjeRecords`, `primaryAudioInterviewUri`, `nextObjeXrefId`.
+- **Constantes** : `GEDCOM_7_EVEN_TYPE_AUDIO_INTERVIEW`, `GEDCOM_7_EVEN_TYPE_ORAL_HISTORY`.
+- **`GedcomExportOptionsEdit.setObjeRecordsById`** / **`clearObjeRecordsById`**.
+- **Tests** : `parseStandaloneObje`, `guessMediFromForm`, `audioInterviewAct`, extension des specs export / import `maximal70`.
+
+### Changed
+
+- **Export OBJE** : émission de `MEDI` dérivé du MIME lorsque absent ; sérialisation multi-fichiers via `formatObjeRecordBlock`.
+- **Import** : `objePayloadById` remplacé par `objeRecordsById` (`PersonGedcomImportOptions`, `ActsByExtraction`).
+- **CI** : script `test:ci` (`build` puis `vitest run`) pour les tests qui lisent `dist/` ; `prepublishOnly` aligné.
+
+### Fixed
+
+- **GEDZIP** : inclusion des binaires locaux liés par pointeur `OBJE` (chemins résolus depuis `sourceUri` / `relativePath`).
+- **FORM audio** : reconnaissance de **WebM**, OGG, WAV, M4A, FLAC, etc. (`guessMediaFormFromUri`, `guessMediaFormFromFile`) ; affinage des exports `application/octet-stream` issus de l’UI.
+
 ## [2026.5.4] - 2026-05-24
 
 ### Added

package/README.md

@@ -6,6 +6,8 @@
 - work with a typed JSON model (persons, acts, dates, places, notes, media, name variants, attributes)
 - edit the model in-place through a fluent, chainable API (`editPerson`, `editAct`, …)
 - export data back to GEDCOM (`.ged`) or GEDZIP (`.zip`)
+- attach **audio** and other media via GEDCOM 7 `OBJE` records (`MEDI AUDIO`, multi-`FILE`, `TRAN`)
+- model **oral history interviews** as `EVEN` acts with `OBJE` + transcription notes
 - geocode event places (OpenStreetMap / Nominatim) and group similar city names
 - generate a **genealogy booklet** as PDF (`gedcom-ts/booklet`, 11 locales including RTL Arabic/Hebrew)
 
@@ -19,13 +21,14 @@ A graphical demo showcasing the public API (import a `.ged` / `.zip`, browse the
 - [Quick start](#quick-start)
 - [Geocoding places](#geocoding-places)
 - [Genealogy booklet (PDF)](#genealogy-booklet-pdf)
+- [Audio and oral history (GEDCOM 7)](#audio-and-oral-history-gedcom-7)
 - [API reference](#api-reference)
 - [Error handling](#error-handling)
 
 ## Package
 
 - NPM: [gedcom-ts](https://www.npmjs.com/package/gedcom-ts)
-- Version format **CalVer** `AAAA.M.micro` (e.g. `2026.5.3` = May 2026). See [CHANGELOG.md](CHANGELOG.md).
+- Current release **`2026.6.0`** — audio / OBJE / oral history. Version format **CalVer** `AAAA.M.micro` (e.g. `2026.6.0` = June 2026). See [CHANGELOG.md](CHANGELOG.md).
 - Entry points:
   - **`gedcom-ts`** — import, model, edit layer, export, geocoding
   - **`gedcom-ts/booklet`** — PDF livret (`pdf-lib` en peerDependency, chargé depuis `node_modules`)
@@ -367,6 +370,65 @@ await drawGedcomTsLogoOnPage(page, defaultCoverLogoOptions());
 | Font preload (host) | `registerBookletPdfFontBytes`, `registerPdfFontkit`, `localeNeedsUnicodePdfFont` |
 | Logo | `ensureBookletLogo`, `drawGedcomTsLogoOnPage`, `getGedcomTsLogoPaths`, `defaultCoverLogoOptions` |
 
+## Audio and oral history (GEDCOM 7)
+
+Since **`2026.6.0`**, gedcom-ts models audio according to [FamilySearch GEDCOM 7](https://gedcom.io/): external files referenced by **`OBJE`** records (`FILE` + `FORM` + optional `MEDI AUDIO` + `TRAN` for alternate formats or WebVTT). Text transcriptions belong in **`NOTE`** under the event, not inside `OBJE`.
+
+**Oral history pattern:** `1 EVEN` + `2 TYPE Interview` (or `Oral history`) + `2 OBJE @O…@` + `2 NOTE` (transcription).
+
+```ts
+import {
+  createAudioInterviewAct,
+  editAct,
+  ExportGedzipFile,
+  type Person,
+  type ReadGed,
+} from "gedcom-ts";
+
+async function addInterview(readGed: ReadGed, person: Person, mp3: File) {
+  const objeMap = new Map(readGed.objeRecordsById);
+
+  const { act, objeRecord } = createAudioInterviewAct(
+    {
+      description: "Entretien avec grand-mère",
+      participantIndis: [person.INDI],
+      ownerIndi: person.INDI,
+      audioFile: mp3,
+      transcription: "Bonjour, je m'appelle Marie…",
+      vttUri: "media/transcript.vtt", // optional FILE.TRAN on OBJE
+    },
+    readGed.persons,
+    objeMap,
+  );
+
+  person.acts.add(act);
+  if (objeRecord) {
+    objeMap.set(objeRecord.id, objeRecord);
+  }
+
+  await new ExportGedzipFile("my-tree", readGed.persons, {
+    extraTopLevelRecords: readGed.preservedTopLevelRecords,
+    objeRecordsById: objeMap,
+  }).download();
+}
+
+// enrich an existing act:
+editAct(act)
+  .asAudioInterview(readGed.persons, objeMap)
+  .setTranscription("Suite de l'entretien…")
+  .attachAudio({ audioUri: "https://example.org/rec.mp3", ownerIndi: person.INDI });
+```
+
+| Goal | API |
+| --- | --- |
+| Create interview act | `createAudioInterviewAct` |
+| Attach audio to act | `attachAudioInterviewToAct`, `editAct(act).asAudioInterview()` |
+| Detect imported interviews | `isAudioInterviewAct`, `isAudioInterviewEvenType` |
+| Read transcription / media | `getAudioInterviewTranscription`, `primaryAudioInterviewUri` |
+| OBJE round-trip | `readGed.objeRecordsById` → `objeRecordsById` in export options |
+| Low-level OBJE parse/emit | `parseStandaloneObjeBlock`, `formatObjeRecordBlock`, `guessMediFromForm` |
+| EVEN type constants | `GEDCOM_7_EVEN_TYPE_AUDIO_INTERVIEW`, `GEDCOM_7_EVEN_TYPE_ORAL_HISTORY` |
+
 ## API reference
 
 Short description and a minimal snippet for each export of **`gedcom-ts`**. For the PDF booklet, see [Genealogy booklet (PDF)](#genealogy-booklet-pdf) (`gedcom-ts/booklet`).
@@ -416,7 +478,7 @@ try {
 
 #### `ReadGed`
 
-Result of an import. Top-level GEDCOM records not modeled into the typed graph (`OBJE`, `REPO`, `SOUR`, `SUBM`, …) are kept in order on `readGed.preservedTopLevelRecords` for round-trip export.
+Result of an import. Standalone `0 @O…@ OBJE` blocks with at least one `FILE` are parsed into **`objeRecordsById`** (multi-file, `MEDI`, `TRAN`). Other top-level records (`REPO`, `SOUR`, `SUBM`, …) stay on `preservedTopLevelRecords` for round-trip export.
 
 Notable members:
 
@@ -430,6 +492,7 @@ Notable members:
 | `placesMap: Map<string, Place>`        | City name → `Place` (first occurrence wins).                                                                                                               |
 | `mapFiles: Map<string, File>`          | Relative path → media `File` (for ZIP imports).                                                                                                            |
 | `datasetVersion: GedcomDatasetVersion` | `"7.0"`, `"5.5"` or `"unknown"`.                                                                                                                           |
+| `objeRecordsById: Map<number, ObjeRecord>` | Parsed `OBJE` records (audio, images, …) keyed by `@O{n}@`.                                                                                            |
 | `preservedTopLevelRecords: string[]`   | Raw blocks for partial round-trip.                                                                                                                         |
 | `resolveIndividualPointer(raw)`        | Resolves `@I12@`, `I12`, `@Homer_Simpson@`, `Homer_Simpson` to a `Person`.                                                                                 |
 | `getChildrenForParent(parent)`         | All children attached to a parent (via `FAMS`).                                                                                                            |
@@ -471,6 +534,7 @@ import { ExportGedcomFile, type ReadGed } from "gedcom-ts";
 function exportGed(readGed: ReadGed) {
   new ExportGedcomFile("my-tree", readGed.persons, {
     extraTopLevelRecords: readGed.preservedTopLevelRecords,
+    objeRecordsById: readGed.objeRecordsById,
     headLanguageTag: "fr-FR",
     headCopyright: "© 2026 Family Archive",
     headDestination: "https://gedcom.io/",
@@ -499,6 +563,7 @@ Options shared by both exporters:
 | Option                 | Effect                                                                                                   |
 | ---------------------- | -------------------------------------------------------------------------------------------------------- |
 | `extraTopLevelRecords` | Raw `0 …` blocks re-emitted before `SUBM` / `TRLR` (round-trip with `readGed.preservedTopLevelRecords`). |
+| `objeRecordsById`      | Full `OBJE` records (multi-`FILE`, `MEDI AUDIO`, `TRAN`) from `readGed.objeRecordsById`.                 |
 | `headLanguageTag`      | BCP 47 tag for `HEAD`.`LANG` (defaults to `en-US`).                                                      |
 | `headCopyright`        | One-line `1 COPR` notice.                                                                                |
 | `headDestination`      | Value of `HEAD`.`DEST` (target app / URI).                                                               |
@@ -644,7 +709,7 @@ const payload = place.toGedcom7PlacPayload(); // "Paris, , Île-de-France, Franc
 
 #### `MultimediaFile`, `MultimediaFiles`
 
-Wraps either a local `File`, an external URI (`sourceUri`) or an OBJE pointer (`objeXrefId`) so the same model can survive a GED / ZIP round-trip.
+Wraps either a local `File`, an external URI (`sourceUri`) or an OBJE pointer (`objeXrefId`) so the same model can survive a GED / ZIP round-trip. See [Audio and oral history](#audio-and-oral-history-gedcom-7) for interview workflows.
 
 ```ts
 import { MultimediaFile, MultimediaFiles } from "gedcom-ts";
@@ -719,7 +784,8 @@ editDateAct(person.acts.list[0].dateAct!).setExactDate(1900, "JAN", 1);
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `editPerson(person)` / `PersonEdit`    | Identity, `FAMS` / `FAMC` / `removeFams*`, `nameVariants()` / `attributes()` / `multimedia()`, bulk `clear*`, entry points to `acts()` and `notes()`.                                                                     |
 | `editActs(acts)` / `ActsEdit`          | `add`, `addNew`, `insertAt`, `insertNewAt`, `replaceAt`, `removeAt`, `removeAct`, `removeLast`, `clear`, `sortByDate`, `at`, `indexOfAct`.                                                                                |
-| `editAct(act)` / `ActEdit`             | `setType`, `setIndis`, dates, place, EVEN fields, preserved lines, `notes()`, `multimedia()`, `clearNotes`, `clearMultimedia`.                                                                                            |
+| `editAct(act)` / `ActEdit`             | `setType`, `setIndis`, dates, place, EVEN fields, preserved lines, `notes()`, `multimedia()`, `asAudioInterview()`, `clearNotes`, `clearMultimedia`.                                                                        |
+| `editAudioInterviewAct(act)` / `AudioInterviewActEdit` | Oral-history facade: `attachAudio`, `setTranscription`, `setDescription`, `registerPendingObje`, `isAudioInterview`, …                                                                                    |
 | `editDateAct(dateAct)` / `DateActEdit` | `clear`, `applyGedcomPayload`, `setExactDate`, `setQualified`, `setBetween`, `setFromTo`, `setTime`, `setDatePhrase` / `appendDatePhrase`, `setVerbatimPayload`.                                                          |
 | `editPlace(place)` / `PlaceEdit`       | `setFromGedcom7Payload`, `setCity`, `setCounty`, `setState`, `setCountry`, `setPlacPhrase` / `appendPlacPhrase` / `clearPlacPhrase`, `setCoordinates` / `clearCoordinates` / `replaceCoordinateModel`, `clearStructured`. |
 | `editNotes(notes)` / `NotesEdit`       | `add`, `addNew`, `insertAt`, `insertNewAt`, `replaceAt`, `removeAt`, `removeNote`, `removeLast`, `clear`, `at`, `indexOfNote`.                                                                                            |
@@ -785,7 +851,7 @@ validateReadGed(readGed, {
 | Export                                                                                                                                                              | Role                                                                                                                                                                                                                                                      |
 | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `editReadGed(readGed)` / `ReadGedEdit`                                                                                                                              | `addPerson`, `removePersonByIndi`, `preserved()` → `PreservedTopLevelEdit` (`append`, `insertAt`, `replaceAt`, `removeAt`, `clear`) on `preservedTopLevelRecords`. Low-level helpers: `addPersonToReadGed`, `removePersonFromReadGedByIndi`.              |
-| `editGedcomExportOptions(opts)` / `GedcomExportOptionsEdit`                                                                                                         | Fluent setters for `extraTopLevelRecords`, `headLanguageTag`, `headCopyright`, `headDestination`, `headSchemaTagDefs`.                                                                                                                                    |
+| `editGedcomExportOptions(opts)` / `GedcomExportOptionsEdit`                                                                                                         | Fluent setters for `extraTopLevelRecords`, `objeRecordsById`, `headLanguageTag`, `headCopyright`, `headDestination`, `headSchemaTagDefs`.                                                                                                                 |
 | `clonePerson(person, newIndi)` / `cloneAct(act)` / `person.clone` / `act.clone`                                                                                     | Deep copies for templates or undo stacks.                                                                                                                                                                                                                 |
 | `nextFamilyId(persons)`                                                                                                                                             | Next internal family id `F`.                                                                                                                                                                                                                              |
 | `createMarriageFamily`, `linkChildToFamily`, `unlinkChildFromFamily`, `removeFamilyReferencesFromDataset`                                                           | Create family `F` and spouse acts; optional `{ eventTag }` (default `MARR`, also `ENGA`, banns, contract, `EVEN` + `CreateActInit`, …). See `GEDCOM_7_PAIR_UNION_EVENT_TAGS`.                                                                             |
@@ -832,12 +898,13 @@ const version = resolveDatasetVersion(headLines); // "7.0" | "5.5" | "unknown"
 
 #### `guessMediaFormFromUri(uri)`
 
-Best-effort media type detection from a path/URI (jpg, png, gif, webp, mp3, mp4, pdf, …). Used internally to fill `OBJE`.`FILE`.`FORM`.
+Best-effort media type detection from a path/URI or local `File` (`file.type` when set). Covers images, **audio** (mp3, **webm**, ogg, wav, m4a, flac, …), video, WebVTT, PDF. Used to fill `OBJE`.`FILE`.`FORM`. Pair with `guessMediFromForm` for `MEDI` (`AUDIO`, `PHOTO`, …). `refineGenericObjeForm` upgrades legacy `application/octet-stream` exports using the file extension.
 
 ```ts
-import { guessMediaFormFromUri } from "gedcom-ts";
+import { guessMediaFormFromUri, guessMediaFormFromFile } from "gedcom-ts";
 
-guessMediaFormFromUri("https://example.com/photo.jpg"); // "image/jpeg"
+guessMediaFormFromUri("media/recording.webm"); // "audio/webm"
+guessMediaFormFromFile(new File(["x"], "take.webm", { type: "audio/webm" })); // "audio/webm"
 ```
 
 #### `extractPersonNameVariants(personLines)` / `extractIndiAttributes(personLines)`
@@ -863,7 +930,7 @@ const primary = selectPrimaryNameVariant(person.nameVariants);
 
 #### `GEDCOM_LIBRARY_VERSION`
 
-CalVer string written in exported `HEAD`.`SOUR`.`VERS` (same value as the npm package version, e.g. `2026.5.2`).
+CalVer string written in exported `HEAD`.`SOUR`.`VERS` (same value as the npm package version, e.g. `2026.6.0`).
 
 ```ts
 import { GEDCOM_LIBRARY_VERSION } from "gedcom-ts";