human-experience-filter-art/docs/USER_GUIDE.md

Human Experience Filter — User Guide

Scope (current build state). Only the catalog + selection core is built so far. This guide covers the one thing you can do today: configure media by hand-authoring and validating catalog records. The automated ingest tool, the tagging/review CLI, and the room player are separate, not-yet-built sub-projects and are not covered here.

---

What "configuring media" means

The installation plays media chosen by where a viewer sets the control knobs. Every piece of media is one record in a catalog file. A record says what the file is, where it lives on the drive, its license, and — the important part — its coordinate in the experience-space. At run time the player will pick the record nearest the knob position; for now, you build and validate that catalog.

The catalog is a single file: catalog/library.jsonl. It is JSON Lines — one JSON object per line, one line per piece of media. Blank lines are ignored.

---

Prerequisites

The commands in this guide need Python 3.11+ and must be run from the repo root, where import hef resolves with no install step. Examples use .venv/bin/python; if you made the project virtualenv they work as-is, otherwise substitute your own python3.

Creating the virtualenv is optional but recommended:

python3 -m venv .venv

---

The record schema

Each line is a JSON object. Twelve fields are required; the rest have defaults and may be omitted.

Required fields

Field	Type	Meaning
id	string	Stable unique id (non-empty). Your choice; keep it unique.
title	string	Human title.
source_url	string	Where the piece came from.
source_archive	string	Origin label, e.g. internet_archive, musopen, librivox.
license	string	One of: public_domain, cc0, cc_by, cc_by_nc.
mode	string	One of: audio, video, av.
left	int	Analytical / verbal axis, 0–4 (see rubric).
right	int	Artistic / abstract axis, 0–4.
dark	int	Somber / heavy axis, 0–4.
light	int	Uplifting / serene axis, 0–4.
duration_s	int	Segment length in seconds (≥ 0).
file_path	string	Path to the media file on the player's drive.

Optional fields (defaults shown)

Field	Default	Meaning
review_status	"proposed"	proposed or approved — whether a human has blessed it.
attribution	""	Required text when license is cc_by or cc_by_nc.
resolution	""	e.g. 1920x1080 (video).
dominant_color	""	Hex color, used by the side walls later.
rationale	""	One-line note on why you chose the coordinate.
reviewed_at	null	Timestamp when approved.
notes	""	Free text.

Validation rules (enforced when you load/save)

• id must be non-empty.
• mode, license, review_status must be one of the allowed values above.
• left, right, dark, light must be integers in 0..4 (booleans are rejected).
• duration_s must be ≥ 0.
• cc_by and cc_by_nc require a non-empty attribution.
• Unknown fields and missing required fields are rejected.

The file referenced by file_path is not checked for existence yet — only the record's structure is validated.

---

The coordinate rubric

The four coordinates are the curatorial heart of the work. Each is a felt judgment on a 0–4 scale. The two pairs are independent knobs, not opposite ends of one slider — a piece can be high on both left and right ("whole brain"), or high on both dark and light ("bittersweet").

Axis	0 means…	4 means…
left	not analytical	strongly analytical / verbal / structured — narration, language, logic, sequence, instruction, documentary, spoken word
right	not artistic	strongly artistic / emotional / abstract — music, abstract visuals, dance, nature, awe, non-verbal, dreamlike
dark	not somber	strongly somber / heavy — ominous, melancholic, night, decay, minor-key, storms, noir
light	not light	strongly uplifting / serene — joyful, hopeful, bright, sunrise, gardens, major-key, calm

mode describes the media's channels: audio (sound only), video (image only), av (both). There is no none record — "None" is a control state the player handles by going dark, not a kind of media.

License stance: prefer public_domain / cc0; cc_by is fine if you record attribution; cc_by_nc only while the installation stays non-commercial.

---

Adding media — two ways

Option A: edit the JSONL file by hand

Append one line per piece to catalog/library.jsonl. A complete example record (formatted across lines here for readability — it must be a single line in the file):

{"id": "nasa-earthrise", "title": "Earthrise", "source_url": "https://archive.org/details/earthrise", "source_archive": "internet_archive", "license": "public_domain", "mode": "video", "left": 0, "right": 4, "dark": 1, "light": 3, "duration_s": 600, "file_path": "/media/nasa-earthrise.mp4", "resolution": "1920x1080", "rationale": "wordless awe, bright Earth on black — strongly right-brain, gently light"}

Option B: use the Python API (validates before writing)

.venv/bin/python -c '
from hef.catalog import Record, append_record
r = Record(
    id="librivox-meditations",
    title="Meditations, Book II (excerpt)",
    source_url="https://librivox.org/meditations/",
    source_archive="librivox",
    license="public_domain",
    mode="audio",
    left=4, right=1, dark=2, light=2,
    duration_s=720,
    file_path="/media/librivox-meditations-ii.mp3",
    rationale="spoken philosophy, verbal and reflective — strongly left-brain",
)
append_record(r, "catalog/library.jsonl")
print("added", r.id)
'

append_record validates the record and raises CatalogError (printing what is wrong) before it writes, so a bad record never lands in the file.

---

Validating the whole catalog

Loading the catalog validates every record. Run this after editing by hand:

.venv/bin/python -c "from hef.catalog import load_catalog; print(len(load_catalog('catalog/library.jsonl')), 'records OK')"

• Prints e.g. 12 records OK if everything is valid.
• Raises CatalogError describing the problem if not. A validation error names the field and reason, e.g. coordinate left=9 out of range 0..4; malformed JSON additionally names the line, e.g. line 4: invalid JSON: ....

---

Sanity-checking selection (optional)

To feel how tagging drives playback, you can ask the selection core which record a given knob position would pick. Coordinates are Coordinate(left, right, dark, light); the second argument is the content-mode selector (audio / video / av / none).

.venv/bin/python -c "
from hef.catalog import load_catalog
from hef.selection import Coordinate, select
lib = load_catalog('catalog/library.jsonl')
pick = select(lib, Coordinate(left=0, right=4, dark=1, light=3), 'video')
print(pick.id if pick else 'nothing')
"

Notes that shape how you tag:

• Selection is nearest-match — every knob position resolves to the closest record, so a sparse catalog still works; you do not need to fill every coordinate.
• select(..., 'none') always returns nothing (the void state).
• Pass approved_only=True to restrict to records whose review_status is approved.

---

Where the media files go

Records point at files via file_path. Those files live on the player's drive, not in this git repo (the repo holds only the catalog metadata). Keep your file_path values consistent with wherever you mount that drive on the machine that will eventually run the room.