Media and Galleries

cr4te scans common media files, groups them by folder, generates thumbnails where needed, and renders static media sections.

Supported Media

Current media extensions:

• Images: .jpg, .jpeg, .png
• Video: .mp4, .m4v, .mkv, .webm
• Audio: .mp3, .m4a
• Documents: .pdf
• Text: .md

README.md is reserved for narrative descriptions and is not rendered as a regular text media item.

Media Groups

Media is bucketed by relative folder. Root media uses the configured default section labels. Nested groups use the folder name as the section title.

Example:

Album/
|-- 01 - Track.mp3
|-- 02 - Track.mp3
|-- extras/
|   |-- cover-study.png
|   |-- booklet.pdf

The tracks are rendered as one audio section. The nested extras media renders as its own group.

Media Ordering

The order of media sections is configurable. The music domain uses audio first. The book domain uses documents first. The film domain uses video first.

Image Sampling

Large image folders can be sampled before rendering.

Strategies:

• none: render no gallery images.
• head: take the first images.
• spread: sample across the sorted image list.
• all: include all images.

The maximum sample count is controlled by media_rules.image_gallery_sample_max.

Gallery Layouts

cr4te has two image gallery layout strategies:

• aspect: fixed aspect-ratio card/grid layout.
• justified: row-based image layout using source image dimensions.

Overview cards use configured aspect ratios. Media image galleries use a justified layout by default.

Thumbnails

cr4te generates thumbnails for:

• Creator overview cards
• Project overview cards
• Creator page project cards
• Portraits
• Covers
• Gallery images

If a source image is missing or unreadable, cr4te falls back to generated default thumbnails where applicable.

Portraits and Covers

Portrait and cover images can be set explicitly in metadata:

{
  "portrait": "portrait.png"
}

{
  "cover": "extras/cover.png"
}

If no path is configured, cr4te selects images using configured basenames:

• portrait_basename: default portrait
• cover_basename: default cover

Portrait auto-detection can be enabled with --portrait-strategy auto.

Video Posters

If a video has an image file with the same stem and an image extension, cr4te uses that image as the poster.

Example:

clip.mp4
clip.jpg

Media Staging

Original image, video, audio, and document files are staged into the output through links.

cr4te tries:

1. Symbolic link.
2. Hard link.
3. Abort.

It does not silently copy media files when links cannot be created, because copying a large archive can be expensive and probably unwanted.

If staging fails, enable symlink permissions or place input and output on the same filesystem so hard links can be used.

Text Media

Markdown files other than README.md are rendered inline as text media sections.