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

Creator and project pages present media as folder-derived groups. The actual root group appears first, followed by groups whose final folder name matches the configured metadata folder. Remaining groups are ordered lexicographically by their complete relative folder paths, which keeps each ordinary folder tree together:

root
meta
a
a/deep
b

Media directly in the creator or project folder and media in the configured metadata folder use root-group section labels.

Within each group, media sections follow the resolved site_rendering.media.type_order configuration. The music domain uses audio first, the book domain uses documents first, and the film domain uses video first. The configured type order does not move media between folder groups.

Audio and Video Playback

Only one audio or video player can play at a time on a generated detail page. Starting another player automatically pauses the previously active player while preserving its source, selected track, and playback position.

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 in card and gallery contexts where applicable. Detail-page portrait and cover roles omit missing or unreadable source images.

Portraits and Covers

cr4te discovers portraits and covers from image filenames. Portrait discovery is configured under media_rules and can be overridden with --portrait-discovery:

• named: select only the lexicographically first image matching media_rules.portrait_basename, preferring direct matches inside the creator folder before nested matches.
• auto: apply named selection first, then select the first eligible portrait-oriented image anywhere below the creator folder, including project folders.

Rendering is controlled separately under site_rendering:

• site_rendering.galleries.creator_cards.display_mode: use image for portrait image cards on the creator overview, or text for text cards with non-zero project and media counts.
• site_rendering.creator_page.show_profile_image
• site_rendering.creator_page.show_member_profile_images
• site_rendering.project_page.show_cover_image
• site_rendering.project_page.show_creator_profile_image
• site_rendering.project_page.show_collaboration_profile_image
• site_rendering.project_page.show_participant_profile_images

These rendering settings do not affect portrait/cover discovery or gallery classification. Detail-page image roles use show, if_available, and hide modes. show renders a source-backed image when possible and falls back to the generated default for that role. if_available renders only source-backed images and omits the role when no usable source image is available. hide omits markup and thumbnail work.

Images matching the portrait basename are reserved for the portrait role rather than gallery media. An image selected by automatic portrait discovery is likewise not duplicated in a gallery.

Covers use media_rules.cover_basename and search only below the corresponding project folder. cr4te prefers direct named matches, then nested named matches, then the first eligible landscape-oriented image, then the first eligible image. If no cover source is selected, card contexts and detail-page cover roles set to show may use generated defaults.

All images matching the portrait basename or a project cover basename are reserved from galleries. Selected portrait and cover fallback images are also reserved, while unselected ordinary fallback candidates remain gallery images. One image may serve multiple selected roles, such as both an automatic creator portrait and a project cover.

Special-image selection uses deterministic case-insensitive lexicographical path ordering, with original spelling as the tie-breaker. Special-role exclusions happen before gallery sampling.

Video Posters

If a video has one or more image files in the same folder with the same case-insensitive stem, cr4te uses the first image in the common deterministic path order as the poster.

Example:

clip.mp4
clip.jpg

All matching poster candidates are reserved from galleries. Poster candidates cannot be selected as automatic portrait or cover fallbacks, but an explicitly named portrait or cover image may also serve as a video poster.

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.