6.3 KiB
File: docs/GALLERIES.md
Version: v0.3.4
Last updated: November 2025
Maintainer: Leak Technologies
Project: Goondex
Goondex Gallery Structure and Metadata Specification
Purpose:
Define how galleries are stored, named, and structured within the Goondex system.
This document standardizes the folder layout, metadata schema, and indexing process to ensure all galleries are consistent and compatible with importer, tagger, and ML modules.
- Directory Structure
All galleries are stored under: ~/Projects/PD/Goondex/Galleries/
Each imported gallery is placed in its own folder: Galleries/<model(s)><short_title>/
Example: Galleries/20251106_1032_Mariella_Sun_Takes_A_Shower/
Inside each gallery folder:
metadata.json → Core metadata record
001.jpg, 002.jpg, ... → Sequentially numbered images
failed_downloads.json (opt.) → List of images that failed to download
thumbnail.jpg (future) → Designated cover image for previews
A global index is maintained at: Galleries/index.json
- Naming Convention
The importer automatically generates folder names using: <shortened_title>
Rules:
- Timestamp format: YYYYMMDD_HHMM (UTC local)
- Model names separated by underscores
- Title truncated to 40 characters max
- Illegal filesystem characters replaced with underscores
- Spaces are converted to underscores
This ensures folder names remain unique, sortable, and descriptive.
- Metadata Specification (metadata.json)
Each gallery includes a metadata.json file containing descriptive fields.
Example: { "title": "Mariella Sun Takes A Shower", "models": ["Mariella Sun"], "categories": ["Amateur", "Shower", "Solo"], "tags": ["Blonde", "Teen", "Wet", "Shower", "Outdoor"], "inferred_tags": ["Amateur", "Solo", "Wet"], "source_url": "https://www.pornpics.com/galleries/12345/", "source": { "network": "PornPics", "channel": null }, "views": 5421, "rating": 4.8, "image_count": 52, "image_urls": [ "https://cdn.pornpics.com/2025/11/12345_001.jpg", "https://cdn.pornpics.com/2025/11/12345_002.jpg" ], "import_path": "~/Projects/PD/Goondex/Galleries/20251106_1032_Mariella_Sun_Takes_A_Shower", "last_refreshed": "2025-11-06T15:40:21Z" }
- Field Definitions
title
→ Human-readable title as extracted from the source site.
models
→ List of performer names detected or scraped from metadata.
categories
→ Source site’s categorical labels (if available).
tags
→ All user and inferred tags combined.
inferred_tags
→ Tags automatically added by the tag_gallery.py module.
source_url
→ The original URL used for import.
source
→ Object with optional "network" and "channel" fields.
Example: { "network": "PornPics", "channel": null }
views
→ Scraped view count from the source (if available).
rating
→ Normalized 0–5 rating (float).
image_count
→ Number of valid images downloaded.
image_urls
→ Full list of image URLs (for re-download or verification).
import_path
→ Absolute path where this gallery is stored locally.
last_refreshed
→ ISO 8601 timestamp marking last metadata update.
- Index File
Galleries/index.json is rebuilt after each import or refresh operation.
It includes essential details for quick CLI lookups and searches.
Example structure: { "galleries": [ { "folder": "20251106_1032_Mariella_Sun_Takes_A_Shower", "title": "Mariella Sun Takes A Shower", "models": ["Mariella Sun"], "tags": ["Blonde", "Teen", "Shower"], "source": "PornPics", "image_count": 52, "last_refreshed": "2025-11-06T15:40:21Z" } ] }
- Refresh and Rebuild Process
When running:
goondex import
→ Imports gallery, creates metadata.json, downloads images, auto-tags.
goondex refresh-one
→ Re-runs tag inference and updates metadata fields.
goondex refresh-all
→ Applies inference and updates to all galleries under Galleries/.
After any import or refresh, index_builder.py:
- Scans all folders for metadata.json
- Builds Galleries/index.json
- Removes stale entries
- Reports summary to console
- Cache and Error Handling
failed_downloads.json
→ Written if any images fail to download.
→ Contains URL and error message for each failure.
Re-importing a gallery with the same title merges metadata:
- Local tags are preserved
- Missing fields (views, rating, etc.) are filled
- Downloaded images are skipped if already present
- Future Enhancements (planned for v0.4.x)
- thumbnail.jpg generation from first image
- Gallery-level previews for upcoming Web UI
- Extended metadata (dominant colours, detected subjects)
- Support for multi-site import with normalized schema
- Developer Notes
Do not manually rename or move gallery folders after import.
Always rebuild the index via CLI if metadata is manually edited.
Each metadata.json should remain human-readable and formatted with indent=4.