Material Workbench · 素材工作台

A local-first creative media workbench for Windows. It indexes videos, images, audio, documents, and selected creative-project files without uploading the library to a cloud service. A native inspiration-card library keeps selected examples, reusable recipes, and production notes beside the catalogue without copying their source files.

素材工作台是一套面向个人创作者的 Windows 本地素材管理工具。视频、图片、 音频、文档和 Adobe 工程都保留在自己的硬盘上，工作台负责索引、检索、预览、 项目归类和经过确认的安全整理。

Why this project exists

Creative projects often spread assets across download folders, project disks, editing applications, and archives. Material Workbench keeps the physical files and the logical catalogue separate:

• Projects, categories, tags, notes, display names, and prompts are metadata.
• Existing library files are not silently renamed, moved, or deleted.
• New intake, storage migration, archive, delete, and exact deduplication are explicit operations with server-side validation.
• Creative applications always retain a host-neutral reveal/copy-path route. Premiere is the first guarded direct-import client boundary, not the product boundary. Its optional external bridge is not bundled with this repository.

Product direction

Material Workbench is an early but serious open-source product. It is not yet a complete replacement for a mature personal asset manager. The direction is a single local library with two equal-capability presentations: a calm visual Browse mode and an explicit batch-oriented Organize mode. Both should connect intake, discovery, creative-app handoff, and reusable inspiration without hiding what happened to the real files.

• Product vision — mission, target user, principles, and deliberate non-goals.
• Product roadmap — outcome-based Now / Next / Later sequencing, not delivery promises.
• Capability status — what is available, improving, planned, exploring, or deliberately out of scope.

Current source (Unreleased)

The current source tree includes media-purpose, startup-safety, and inspiration-card changes that have not yet been assigned a release version:

• Browse/Home now has a first-level Documents entry beside video, image, and audio.
• Browse and Organize open the same type-scoped category manager for video, image, audio, and documents. It supports create, rename, delete, restore, and discard with revision/CAS conflict protection.
• A deleted category keeps a bounded recovery receipt. Restore only reassigns former members that are still uncategorised, so later manual decisions are never overwritten; discarding a receipt does not change an asset.
• Both presentations use the same type-first batch assignment path. In a mixed selection only the chosen media type changes, and the other items are reported as skipped.
• A video's explicit media-purpose category is the primary Browse grouping. Browse falls back to a labelled legacy video status only when that category is empty. The category manager always keeps a separate read-only legacy-status reference block; it does not treat those fixed values as editable purpose categories.
• Startup now checks the read-only /api/bootstrap/status contract before any catalogue is loaded. The diagnostic does not scan, repair, install, or write anything. Only when the server explicitly reports a source as missing may the browser synthesize its documented empty shape; an invalid or unreadable source blocks normal loading instead of hiding damage behind an empty workbench.
• Optional dependency failures gate only the affected capability. Missing Pillow, FFmpeg, or ffprobe disables a complete library refresh; missing Send2Trash disables Recycle Bin operations; an unavailable Premiere connector disables guarded direct import while host-neutral handoff remains available.
• The visible inspiration-card editor now supports 0 to 6 ordered local-media, indexed-document, or URL references. Local items are selected from the current catalogue instead of entered as IDs or paths; an available image or video may be pinned as the one leading cover.
• Recycle Bin deletion now pauses when a selected source is referenced by a v1 or v2 card. The user confirms that relationship against a fresh inspiration revision; this gate composes independently with the existing Adobe dependency confirmation.
• The top-left brand now opens a local Daily Oracle only after an explicit click. It offers the traditional 22-card Major Arcana framework and an original constellation deck; a result is stable for the user's local day, while deck preference and a random browser salt stay only in localStorage.

The category and inspiration-card editing operations above change logical metadata only, while startup diagnostics are read-only. None of those actions moves, renames, or deletes media files. Recycle Bin deletion is the only file-moving action in this section: after explicit confirmation and fresh revision revalidation, it moves the selected source file to the Windows Recycle Bin; the card and its stored reference remain and display as missing. The already verified physical project-media migration still uses its legacy video-status directory projection; changing that transaction requires a separate preview, dependency, journal, rollback, and validation checkpoint.

v0.2 foundation

v0.2.1 is a data-integrity patch: deleting a media-purpose category now affects only authoritative assets of the selected media type. The roadmap documents shipped with the patch describe direction, not completed features.

• Local HTML/CSS/JavaScript interface with a Python standard-library server.
• Video, image, audio, and document indexing with searchable metadata.
• Project and media-purpose views with fixed pagination and continuous preview.
• Desktop intake defaults to a library copy that preserves the original path; moving the original remains an explicit warned choice.
• Transactional project-media migration with journal, backup, and rollback.
• Exact duplicate cleanup using SHA-256 plus byte-for-byte verification.
• Reparse-point, hard-link, path-boundary, stale-plan, and concurrent-write defenses.
• Optional read-only PR / AE / PSD project browser.
• Optional guarded Premiere client boundary; direct import still requires a separately configured compatible bridge.
• Native inspiration-card library for examples, reusable recipes, and production knowledge, with optional links to local assets/documents or URLs.
• 500+ Python safety tests and Node bridge contract tests.

Works without AI

The core workbench does not require an AI account, model API, MCP server, or hosted service. Indexing, search, previews, project organisation, inspiration cards, the optional Daily Oracle, intake, migration, deduplication, and archive planning remain ordinary local application features.

An AI coding or creative Agent can be used as an optional collaborator: it may draft tags, descriptions, project structures, prompts, or inspiration-card content. Suggestions do not become user metadata until the user reviews and adopts them through the workbench, and an Agent is never a prerequisite for the daily workflow.

Platform and maturity

• Currently Windows 10/11 only.
• Source checkout application; this is not yet distributed as a Python wheel.
• Python 3.11 through 3.13; CI currently tests 3.11 and 3.13.
• FFmpeg/ffprobe are required for video metadata and thumbnails.
• Node.js 22 is only required for the optional Adobe bridge and the complete development test suite.

Quick start

The repository and media library may live in different directories. The layout below keeps them together for a simple first install:

New-Item -ItemType Directory -Force D:\MediaLibrary | Out-Null
git clone https://github.com/mirror4869/material-workbench.git D:\MediaLibrary\_video_index
Set-Location D:\MediaLibrary\_video_index

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Copy-Item .\workbench.config.example.json .\workbench.local.json
notepad .\workbench.local.json

Set library_root to the parent directory containing this checkout. Leave the optional Adobe paths and the legacy Promptsref fallback path empty if you do not use them. The native inspiration-card library does not need a Promptsref installation. Never put passwords, API keys, or bridge tokens in the config file.

Create the initial indexes, then start the development server:

ffmpeg -version
ffprobe -version
.\.venv\Scripts\python.exe .\scan_and_thumb.py
.\.venv\Scripts\python.exe .\scan_media.py
.\.venv\Scripts\python.exe .\scan_docs.py
.\.venv\Scripts\python.exe .\serve_gallery.py 8776

The terminal prints the exact local URL. With the folder name above it is:

http://127.0.0.1:8776/_video_index/index_v2.html

Alternatively, double-click workbench_launcher.vbs after configuration. The tray launcher prefers .venv, starts the backend without a console window, and opens an Edge app window when Edge is available.

Safe first run

Use an empty test library before pointing the workbench at valuable media. scripts/create_demo_library.py creates a synthetic local library under .demo/ without reading your existing media:

.\.venv\Scripts\python.exe .\scripts\create_demo_library.py
$env:MWB_CONFIG = (Resolve-Path .\.demo\workbench.local.json)
.\.venv\Scripts\python.exe .\scan_and_thumb.py --metadata-only
.\.venv\Scripts\python.exe .\scan_media.py
.\.venv\Scripts\python.exe .\scan_docs.py
.\.venv\Scripts\python.exe .\serve_gallery.py 8776

The demo generator creates abstract images, a WAV tone, and fictional text. It does not copy any media from your computer.

Before loading the five local data sources, the browser requests the no-store, read-only /api/bootstrap/status diagnostic. That request reports platform, configuration, library, catalogue, optional dependency, project-root, and connector readiness; it does not scan, repair, install, or write files. A source is synthesized as an empty object only when the diagnostic explicitly reports it as missing. Any invalid or unreadable source blocks catalogue loading and keeps the background workspace inert until the problem is resolved.

Optional dependencies degrade only their own guarded actions, so ordinary browsing can still start when the core catalogues are safe. A backend version without this endpoint uses the strict compatibility path: the browser fetches and validates every legacy data file and preserves each operation's existing runtime guard instead of guessing that a missing file is empty.

Configuration

Machine-specific settings are loaded in this order:

1. MWB_* environment variables.
2. The JSON file selected by MWB_CONFIG.
3. workbench.local.json beside the source.
4. Safe local defaults for optional features.

workbench.local.json, runtime indexes, thumbnails, journals, logs, and user metadata are ignored by Git. See configuration and data safety for the full boundary.

The component layout and request flow are summarized in architecture.

Native inspiration-card library

The Inspiration workspace is a first-party part of Material Workbench, not an embedded third-party website. Cards can be organised as an example, a reusable recipe, or a knowledge note. They support search, tags, custom ordering, pagination, create/edit/delete, and one-click recipe copying.

The backend, persistence core, and visible editor are compatible with both inspiration-card v1 and v2. A card can have 0 to 6 ordered references to local media, indexed documents, or http/https URLs. A card has at most one explicit cover; when present, it is the first reference and must resolve to a currently available local image or video. Local items are chosen through the catalogue picker: the UI does not expose an internal-ID or filesystem-path input. Labels are derived by the server rather than trusted from the browser, and URL references are recorded as text without being fetched.

The compatibility boundary is intentionally narrow. Reading, searching, previewing, or opening the editor never upgrades a v1 registry. A text-only edit to a v1 card still submits v1. The browser explicitly selects v2 only when the user actually adds, removes, reorders, or changes a reference or cover and then saves. A registry already stored as v2 remains v2 for every mutation. When an older backend omits the explicit multi_ref_v2 capability, all rich reference mutations and v2 saves fail closed while compatible v1 text editing remains available.

Reading an existing v1 registry is zero-write. The first client request that explicitly selects v2 creates a dedicated verified pre-upgrade backup, upgrades the registry and applies the requested operation in memory, then performs one atomic save with the registry revision increasing by one overall. Controlled storage migration remaps every matching local media/document reference in either schema, while exact deduplication inspects every local asset reference, not only the first source. Creating or deleting a card never copies, moves, renames, edits, or deletes its source.

Ordinary Recycle Bin deletion now checks every v1 or v2 local card reference before moving a selected source. A match returns only safe card summaries and the current inspiration-registry revision. Confirmation recomputes the relationship under the server lock and fails without moving a file if that revision has changed. This is an independent gate from Adobe dependency confirmation; both revisions must remain valid when both relationships exist. After a confirmed deletion the card and its stored reference remain unchanged, and the unresolved local source is displayed as missing.

The old promptsref_root configuration and read-only /promptsref/... route are retained only as a hidden legacy rollback path. They are not the visible inspiration workspace, are not required, and their content is never bundled in the public repository.

Daily Oracle (Unreleased v0.3 candidate)

Daily Oracle is a small local ritual opened from the top-left brand. It never opens on startup and is not restored as an open dialog by the safe browser session. The bundled choices are:

• a traditional deck using the public-domain names and symbolic framework of the 22 Major Arcana, with project-authored short interpretations; and
• an original Material Workbench constellation deck with project-authored cards and text.

The draw uses the selected deck, the user's local calendar date, and a normally random per-browser salt so the result remains stable for that day without a server request. Only the deck preference and salt are stored in browser localStorage; if random generation or storage is unavailable, a fixed non-identifying fallback preserves daily stability without becoming an authorization, tracking, or cross-device identity value. The result is not written to user_data.json, an index, an inspiration card, a project, or a material file. The feature does not call an AI model, fetch remote content, or gain filesystem authority.

The current art direction is deliberately a functional visual prototype: two original card backs, one shared text-led front template, and a bounded CSS flip and light sweep. It does not yet include 43 individually illustrated fronts, a complete visual system for both decks, or WebGL/material-map lighting.

Current-source browser verification covers 1280×720 desktop and 520×760 narrow layouts, both decks, same-day stability across deck changes, close/reopen, and full reload, keyboard focus cycling and return, Escape, and reduced motion. The reload-and-dialog trace contained 52 GET requests, zero POST requests, and zero console warnings or errors. This verifies the visible source feature; it does not mean that v0.3 has been published.

Both decks are for entertainment and self-reflection only. Their text is not medical, legal, financial, safety, or other professional advice. The two card backs are original project assets; the traditional deck does not copy the art, wording, branding, textures, or motion of an existing deck or website. See asset provenance. This source feature is not a published v0.3.0 release.

Optional Adobe integration

The core workbench does not require Adobe software, Node.js, or MCP. Premiere import is enabled only when a separate compatible bridge is configured and the runtime advertises the required same-project guard. The external bridge is not distributed or licensed by this repository. See Adobe integration.

Development

Install dependencies, then run:

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
node --check assets\js\theme-init.js
node --check assets\js\workbench-catalog.js
node --check assets\js\workbench-query.js
node --check assets\js\workbench-bootstrap.js
node --check assets\js\workbench-oracle.js
node --check assets\js\workbench.js
node --check scripts\adobe_import_bridge.mjs
node --check scripts\benchmark_catalog_scale.mjs
node --check scripts\benchmark_query_scale.mjs
node --test tests\node_adobe_import_bridge.test.mjs tests\node_workbench_catalog.test.mjs tests\node_workbench_query.test.mjs tests\node_workbench_bootstrap.test.mjs tests\node_workbench_oracle.test.mjs tests\node_material_query_adapter.test.mjs tests\node_render_coordinator.test.mjs tests\node_inspiration_v2_frontend.test.mjs
git diff --check

Tests use temporary directories and mocks. They must never read or change a real media library.

An optional in-memory scale report uses only synthetic records and the same catalogue-index module loaded by the browser:

node scripts\benchmark_catalog_scale.mjs
node scripts\benchmark_query_scale.mjs

The browser's build-free script order is catalogue → query → bootstrap → oracle → main. workbench-query.js is an independently tested pure query core. The separate assets\js\workbench-bootstrap.js module validates startup diagnostics, data shapes, empty-source plans, and capability gates before the main script loads runtime data. Organize/Material uses an equivalence-tested adapter with explicit display-name, project-category, clock, and sort-profile context; Browse/Home remains on its legacy implementation until its own migration checkpoint. The query fingerprint represents static filter/order state only; a result cache must also include catalogue and metadata revisions, project-category revision, the presentation sort profile, and a time bucket when rolling date filters are active.

assets\js\workbench-oracle.js is a separate pure helper containing static deck data and deterministic daily-selection functions. It does not read the DOM, network, catalogue, or human metadata; browser preference wiring remains in the main script.

Security model

This project treats file operations as security-sensitive:

• Browser requests submit opaque IDs instead of client paths for destructive or Adobe write operations.
• The server rebuilds an authoritative catalogue before acting.
• Existing files are never overwritten during intake or migration.
• Exact deduplication requires content equality, a fresh one-time plan, final revalidation, a persistent journal, and Windows Recycle Bin cleanup.
• A local item referenced by an inspiration card is treated as protected during exact deduplication; ambiguous groups with multiple protected copies fail closed.
• Unknown recovery states fail closed and keep write operations locked.

Please report vulnerabilities privately according to SECURITY.md.

Contributing

Contributions are welcome. Read CONTRIBUTING.md and the public AGENTS.md safety rules before changing file operations, runtime data, or Adobe integration.

License

Licensed under the Apache License 2.0. Visual asset provenance and unbundled runtime dependencies are documented in ASSET_PROVENANCE.md and THIRD_PARTY_NOTICES.md.