Multimedia

A genealogy file is rarely just text — it’s the photographs, certificates, and scanned pages behind the facts. GEDCOM records those as multimedia objects (OBJE), and these recipes go from attaching your first photo to recording its format, cropping a region of it, and bundling every file into one archive on export.

New to reading GEDCOM lines? Skim How GEDCOM works first — every recipe shows the underlying lines, but the app writes them for you as you type.

Create a multimedia object and attach it to a record

The structure. A media object is an OBJE record. It names a file and (where the version allows) that file’s format, then any record that wants the image points at it:

0 @O1@ OBJE
1 FILE images/jane-smith-portrait.jpg
2 FORM image/jpeg

0 @I1@ INDI
1 NAME Jane /Smith/
1 OBJE @O1@

The OBJE record holds the file; the 1 OBJE @O1@ pointer under the person is a multimedia link. Keep the file in one record and point at it from as many people, families, or sources as you like — nothing is copied.

In the app. Use Add Record (in the Edit menu, or the split button in the toolbar) and choose OBJE – Multimedia; a new record opens ready for a FILE line. To link it from a person, add an OBJE line to that record in the editor — autocomplete offers it, and ⌘/Ctrl-click on the pointer jumps to the media record. The inspector’s Media view shows every object attached to the selected record with a thumbnail, and the file manager lists the actual files alongside your .ged.

Across versions. OBJE is a record in all three versions, but its insides differ sharply — that is the subject of the next recipe. In 5.5 the file’s FORM sits directly under OBJE; in 5.5.1 and 7.0 the record holds one or more FILE lines, each with its own FORM beneath it. A 1 OBJE @O1@ pointer works the same everywhere.

Validation notes. A media link that points at a missing @O…@ record is flagged as a broken reference. An OBJE record needs a FILE (5.5.1 / 7.0) — or, in 5.5, embedded data; see Link a file vs. embed it. The FILE value should resolve to a real file in your project; the file manager shows which records reference which files.

Link a file vs. embed it

Goal. Decide whether the media object references an external file or carries the image bytes inside the GEDCOM — and understand why only one old version even offers the second choice.

The structure (link — 5.5.1 and 7.0). A FILE line names the file; the bytes live outside the GEDCOM. The record shape is the same in both versions — only the FORM value differs, a short code in 5.5.1:

0 @O1@ OBJE
1 FILE images/marriage-certificate.tif
2 FORM tif

…and a MIME media type in 7.0:

0 @O1@ OBJE
1 FILE images/marriage-certificate.tif
2 FORM image/tiff

The structure (embed — 5.5 only). GEDCOM 5.5 could carry the encoded image inline, in a BLOB:

0 @O1@ OBJE
1 FORM jpeg
1 BLOB
2 CONT /9j/4AAQSkZJRgABAQEAYABg…

In the app. Linea Codex always works from external files — you upload photos and scans into the project with the file manager and reference them with FILE. When you import a 5.5 file that contains BLOB data, the app extracts each embedded image to a real file so you can view and crop it; the file manager marks those as Extracted, and (per its own note) “Embedded files are extracted for viewing. They will be re-embedded automatically when you save.” So you never hand-edit BLOB text.

Across versions. This is the single biggest multimedia change between versions:

5.5 supported embedded media via BLOB (with a FORM at the OBJE level), and could also reference external files.
5.5.1 eliminated BLOB entirely — the spec states “the BLOB tag was eliminated” — in favour of FILE references. There is no inline media in 5.5.1.
7.0 keeps the FILE-reference model and likewise has no BLOB.

Conversion is best-effort, and the direction matters. Converting 5.5 → 5.5.1 / 7.0, Linea Codex lowers each extracted BLOB to a FILE reference (it uses an internal _EMBED marker to remember the extracted path, then reshapes it to FILE) — the convert preview reports this as media “saved as external files.” Converting down to 5.5, the app re-embeds a referenced file as a BLOB only when that file is recoverable in the project; an external or missing file has nothing to embed, so its media record is dropped with an explicit warning. Never assume a downgrade is lossless.

Validation notes. A BLOB in a 5.5.1 or 7.0 file is flagged — the tag isn’t valid there. An OBJE with no FILE and no embedded data is an empty media record. In 5.5, an inline OBJE without a FILE shows in the inspector as “Inline OBJE without FILE — embedded BLOB not previewable here,” which is your cue that the data is embedded rather than linked.

Record a file’s format and media type

The structure. Two distinct facts describe a media file: its format (FORM — what kind of file it is) and the medium of the original (MEDI — was it a photograph, a microfilm, an audio recording). Where they nest, and what values they take, is version-specific.

0 @O1@ OBJE
1 FILE images/census-1880.jpg
2 FORM image/jpeg
3 MEDI ELECTRONIC

In the app. Type the FILE line and autocomplete offers FORM beneath it (and MEDI beneath that), with the values valid for your file’s version. The spec viewer is one click away to confirm a tag’s valid structure and its allowed values.

Across versions. FORM changes both where it sits and what it means:

5.5 — FORM sits directly under OBJE (1 FORM), and its value is a short format code: bmp, gif, jpeg, ole, pcx, tiff, or wav.
5.5.1 — FORM moves under the FILE line (2 FORM), still a short code (the 5.5.1 set is bmp, gif, jpg, ole, pcx, tif, wav). A MEDI (source media type) may nest under FORM, drawn from a lowercase enumeration: audio, book, card, electronic, fiche, film, magazine, manuscript, map, newspaper, photo, tombstone, video.
7.0 — FORM is still under FILE but its value becomes a MIME media type (e.g. image/jpeg, application/pdf), and it is required for every FILE. MEDI nests under FORM as an uppercase enumeration: AUDIO, BOOK, CARD, ELECTRONIC, FICHE, FILM, MAGAZINE, MANUSCRIPT, MAP, NEWSPAPER, PHOTO, TOMBSTONE, VIDEO, or OTHER (with a PHRASE describing the “other” case).

Converting between versions rewrites FORM accordingly — short code ↔ MIME type — and maps the MEDI enum’s case (photo ↔ PHOTO) as faithfully as it can; the version-change confirmation spells this out (“BLOB ↔ FILE, FORM codes ↔ MIME types”). Best-effort, as ever: a 7.0 MIME type with no short-code equivalent has no perfect 5.5 form.

Validation notes. In 7.0, every FILE requires a FORM, and the FORM value should be a well-formed media type; a MEDI value outside the enum is flagged as an invalid enumerated value. In 5.5 / 5.5.1, a FORM value outside the short-code set is flagged. Putting FORM directly under OBJE is correct only in 5.5; in 5.5.1 / 7.0 it belongs under FILE.

See also: Link a file vs. embed it · The spec viewer.

Crop a region of an image

Goal. Display only part of an image — one face in a group portrait, one signature on a deed — without altering the file itself.

The structure (7.0 only). A CROP under the media link (not the media record) names a rectangular region in pixels:

0 @I1@ INDI
1 NAME Jane /Smith/
1 OBJE @O1@
2 CROP
3 TOP 120
3 LEFT 80
3 HEIGHT 400
3 WIDTH 300

LEFT and TOP give the top-left corner of the region; WIDTH and HEIGHT give its size. Each is a number of pixels, and each is optional — omit LEFT/TOP and they default to 0; omit WIDTH/HEIGHT and they extend to the image’s edge.

In the app. Open the image and use the crop tool: Set crop opens it, you drag a region or enter Top, Left, Width, Height in pixels, then Apply; Remove crop clears it. A cropped link shows a Cropped marker (and a CROP badge in the inspector’s media list). Cropping is version-gated — in a non-7.0 project the tool reports “Crop is only available for GEDCOM 7.0 projects,” and it’s image-only (“Crop is only available for image files.”).

Across versions. CROP (with TOP, LEFT, HEIGHT, WIDTH) is a 7.0 addition — it does not exist in 5.5 or 5.5.1. The crop lives on the link from a record to a media object, so the same image can be cropped differently for different people. Converting a 7.0 file down to 5.5.1 or 5.5 drops the CROP — best-effort; the underlying media link survives, but the region is lost.

Validation notes. Because the crop is pixel-based, the region must fit inside the image: LEFT or LEFT + WIDTH exceeding the image width (or TOP/HEIGHT exceeding its height) is an error, surfaced in-app as “CROP region extends beyond the image.” A zero-area region can’t be applied. CROP only applies to an external image file with a known pixel size — applied to a non-image, it’s flagged. A CROP in a 5.5 / 5.5.1 file is flagged as a tag that isn’t valid there.

Bundle media with your file on export

Goal. Hand someone your whole project — the GEDCOM and every photo and scan it references — as one file, rather than a .ged with broken FILE paths.

The structure. There’s nothing new to write in the records: a GEDZIP is simply a ZIP archive that contains the GEDCOM file (as gedcom.ged) together with the local files its FILE lines reference, each at the relative path the GEDCOM names. Your FILE values stay exactly as they are:

0 @O1@ OBJE
1 FILE images/jane-smith-portrait.jpg
2 FORM image/jpeg

On opening the archive, that images/jane-smith-portrait.jpg is right there beside the GEDCOM.

In the app. Use File → Export as GEDZIP to produce the bundled archive, or Export as ZIP for a plain archive of the project folder. Plain Export / Export As… writes the GEDCOM file by itself, leaving FILE references pointing at files you’d have to send separately. See Saving & exporting your project for the full menu.

Across versions. GEDZIP is a 7.0 feature — the packaging convention was introduced with GEDCOM 7.0, so it’s the version to export when you want a single self-contained file. For 5.5 / 5.5.1 you can still bundle the project as a plain ZIP, but there’s no standard GEDZIP container; recipients reassemble the GEDCOM and its media by relative path.

Validation notes. GEDZIP relies on FILE values being project-relative paths that actually resolve to files in your project — an absolute path, or one that escapes the project root, can’t be packaged. Keep media inside the project folder (the file manager enforces this) so every referenced file travels with the export. Embedded 5.5 BLOB data doesn’t apply here — once extracted, it’s an ordinary file that bundles like any other.

Next: where sources live and who compiled the file — Repositories & submitters.