⚠️ Under Construction This project is still in development. Features, structure, and configuration may change without notice.

A fast, static site generator for organizing and showcasing media collections.

cr4te scans your existing folder structure, extracts metadata and media (images, videos, audio, documents), and generates clean, responsive HTML galleries. With built-in search, tagging, filtering, and pagination, it's ideal for archiving, browsing, or publishing rich media portfolios—no manual curation or database required.

View full gallery

If you find cr4te useful, consider donating via PayPal to help support continued development.

• Automatically builds a gallery website from your existing folder structure (e.g. directors and movies)
• Dedicated overview pages with filter and tag-aware search
• Video, audio, image, and document organization with dynamic labels
• HTML domain presets for different domains (art, music, books, film, ...)
• User-customizable labels and media rules via optional config file
• Fast static HTML output with no runtime dependencies during browsing
• Theme switcher

This tool is an ongoing work-in-progress. Expect improvements, breaking changes, and new features.

Your folder structure should follow a nested, hierarchical format that reflects creators and their projects. For example:

Domain/
├── Alice/
│   └── Project1/            # Media folder (images, videos, documents,...)
├── Bob/
└── Bob & Charlie/           # Collaboration folder
    └── ProjectZ/            # Media folder

This could represent domains like:

• Music → Musician → Album
• Library → Author → Book
• Movies → Director → Film
• Design Portfolios → Designer → Project

...and so on.

Each leaf folder (e.g., Project1, ProjectZ) contains the media and optional metadata used to build the final site.

git clone https://github.com/vger-6/cr4te.git
cd cr4te
pip install -r requirements.txt

See also the Quick-Start which includes a step-by-step guide using example data.

⚠️ Note cr4te.json files are automatically generated by the build command and saved directly into each creator’s original folder (e.g., <input_folder>*/cr4te.json). These files can be manually edited to override or extend metadata such as birth dates, aliases, tags, or project descriptions.

⚠️ Note Ensure that <output_folder> does not already exist, as it will be deleted!

python cr4te.py build -i <input_folder> -o <output_folder>

See Troubleshooting if something is not working.

python cr4te.py build -i <input_folder> -o <output_folder> --config path/to/my_config.json

python cr4te.py build -i <input_folder> -o <output_folder> --domain film

Available presets:

• art (default)
• film
• music
• book

If --config is not specified, cr4te uses internal defaults.

Additional options:

• --image-sample-max — Set maximum images per media group (overrides config). The default is 20
• --image-sample-strategy — Image selection strategy: spread, head, all
  • spread (default): even sampling throughout the list
  • head: take the first N images
  • all: take all images

If --image-sample-strategy all is used --image-sample-max has no effect.

Your configuration file should be in JSON format and can override labels and media matching rules. Use the --print-config flag to print a config file on screen or redirect it to a json file for further adjustment and later use.

python cr4te.py build [options] --print-config > my_config.json

Each creator folder must contain a cr4te.json file. The cr4te.json files are automatically generated by the build sub command. Some fields can be edited by hand.

See this cr4te.json file from the example.

• born_or_founded: Must be in YYYY-MM-DD format
• active_since: Must be in YYYY-MM-DD format
• nationality: Any free-form text
• aliases: List of alternate names
• info: Optional bio text (supports Markdown)
• tags: Format should be Category:Tag, e.g. Occupation:Photographer. Photographer without a category works too.
• projects[*].info: Optional per-project description
• projects[*].tags: Tag list for each project
• members: If this is a group folder, add member names
• collaborations: Add collaboration names

⚠️ Note Other fields might be overridden automatically during the build process. Editing those fields by hand is futile.

• index.html — Overview page
• projects.html — Projects overview page
• tags.html — Browse by tags

Thumbnails and HTML pages are automatically generated into /thumbnails/ and /html/ repectively.

• Python 3.10+
• Pillow
• Mutagen
• Markdown
• Jinja2
• Pydantic

Some browsers (notably Firefox with strict settings) block localStorage access across pages loaded with the file:// protocol.

Solution: run a lightweight local server from your output folder:

cd /path/to/OutputFolder
python3 -m http.server 8000

Then open http://localhost:8000/ in your browser.

This will fix localStorage issues and better match how your site behaves when deployed online.

If running the build command doesn't work or fails silently, it may be due to insufficient file permissions. Try running the command with administrator privileges (e.g., using sudo on Unix-based systems or an elevated Command Prompt on Windows).

Also, ensure:

• The output directory is writable.
• All required dependencies are installed.

Current version: 0.0.1

This project is licensed under the terms of the LICENSE file included.

Contributions are welcome! Please open an issue or submit a pull request.