Create Media
create_mediaUpload photos, scans, or PDFs from server upload folders as media records and attach them to people, families, events, places, sources, or citations, including selected image regions.
Instructions
Upload a photo, document scan or PDF from the server's upload folder as a new media record, and show it on people, families, events, places, sources or citations with attachTo, whole or as a region such as one record on a page scan. Only files inside GRAMPS_MEDIA_UPLOAD_DIRS can be uploaded, and a relative filePath is looked up in each of them in turn; the type (JPEG, PNG, GIF, WebP, TIFF, BMP or PDF) is judged by content. citationHandles cite where the file itself came from, while attachTo shows it on the records it documents, such as a citation with the region of its entry. If the tree already stores an identical file (same MD5 checksum), nothing is uploaded: that record is returned with action existing, its fields stay as they are and only attachTo is applied, so repeating a call is safe. Returns the handle and Gramps ID; an unreadable date or unknown attachTo record is rejected before anything is uploaded. It is the only tool that uploads a file: create_records takes no media, and a transcription of a document belongs in a note (create_note), not here. Change the record later, or swap its file, with update_media; check what a region shows with read_media. Writes run one at a time and need a Gramps Web account allowed to edit the tree; a locked or rate-limited write fails with the delay to wait before retrying it. Formats of every argument: get_reference(topic: "input-guide").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date of the photo or document. Date text: 1856-07-20, 1920-05, 1920, 1 Jul 1919, about/before/after 1920, 1800-1850, between … and …; append the calendar for other calendars, e.g. 1856-07-20 (Julian). Unreadable dates are rejected. | |
| attachTo | No | Records to show the media on, each getting a link after its existing media: Gramps IDs (I0001, F0001, E0001, P0001, S0001, C0001) or handles of people, families, events, places, sources or citations. JSON array, one value, or a comma-separated string. To show only part of the image, such as one record on a page scan, give an object {"ref":"I0001","region":[left, top, right, bottom]} in place of the ID. A region is [left, top, right, bottom]: its edges in percent of the image width and height, 0 to 100, measured from the top-left corner; [10, 20, 60, 45] runs from 10% to 60% across and from 20% to 45% down. A record already showing the media keeps its link and takes the region; list a record twice to show two regions. Check a region with read_media first. | |
| filePath | Yes | The file to upload: an absolute path inside an upload folder, ~/…, or a name relative to the folder, e.g. scan.jpg. | |
| isPrivate | No | Mark the media private (default false). | |
| attributes | No | Attributes. Attributes: JSON array of objects {type,value,...}, or strings "Type: Value" (first colon), or one string with lines or | between entries. A type must be a standard Gramps attribute type or a custom one the tree already uses; anything else is rejected with suggestions. Full grammar: gramps://input-guide. | |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| description | No | Description (caption). Default: the file name without its extension. | |
| noteHandles | No | Notes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| citationHandles | No | Citations for the media itself. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |