looks 0.0.1__tar.gz

looks-0.0.1/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

looks-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@0.2.15`;
+# tags have no `v` prefix). A stub whose `secrets:` block passes the JSON
+# transport (the default below) needs a tag from a release after 0.2.14 —
+# older tags don't declare that secret and GitHub then rejects the
+# workflow at parse time.
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Transport: NAMED secrets, not the whole `secrets` context.
+    #
+    # The generated default is `WADS_CI_SECRETS_JSON: ${{ toJSON(toJSON(secrets)) }}`,
+    # which hands the reusable workflow every secret this repo can read. In a
+    # NEW repository that trips GitHub's malicious-workflow scanner — the run
+    # is created, then held with conclusion `action_required` and ZERO jobs,
+    # and the only place the reason appears is the run's HTML page:
+    # "GitHub detected that this workflow file may be malicious. It will not
+    # run until someone with write access approves it."
+    # `gh run view`, the jobs API, the check-runs API and the annotations API
+    # are all silent, and `POST .../approve` refuses ("not from a fork pull
+    # request"), so the run cannot be released from the CLI at all.
+    #
+    # Naming the three secrets this repo actually has both clears the scanner
+    # and is the smaller surface, which is what `wads-migrate ci-to-stub
+    # --transport named` exists to produce. Add a line here when you add a
+    # secret; an absent name is simply empty (every input is `required: false`).
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+      SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

looks-0.0.1/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

looks-0.0.1/KICKOFF.md

@@ -0,0 +1,96 @@
+# looks — kickoff
+
+*Written 2026-09-02 by the session that built the Que Calor music videos and hit the gap this package fills. Delete this file once `docs/` and `README.md` carry its content.*
+
+## What this is
+
+A **facade over video stylization** — named effects that compile to a backend command, with a per-effect **licence tier** so a caller can demand "commercial-safe only" and get a refusal rather than a surprise.
+
+PyPI has ~8 ffmpeg wrappers. None of them is this. The two missing things:
+
+1. **A registry of named effects carrying a licence tier.** Every existing wrapper assumes you know what you're linking.
+2. **Pure-data effect specs, separable from execution** — the `falaw.Plan` shape. A `Look` should be inspectable, persistable, diffable and *costable* before anything runs.
+
+**It is an extraction, not greenfield.** `muvid/visualize/visuals.py` already has ~80% of the shape: a frozen `VisualPlan` (ffmpeg inputs + filter chains + output label), a `register_visual` open-closed registry, and an escape hatch for non-ffmpeg backends that return a rendered path. Generalise that from *audio→video* to *video→video*. Read it before designing anything.
+
+Background: **thorwhalen/muvid#63** is the proposal issue and has a long comment recording a measured design constraint (below). Read both.
+
+## Non-negotiables
+
+- **Zero hard media dependencies.** `pyproject.toml` declares nothing but stdlib; every backend is an optional extra. Specifically **never** depend on `av` (its wheel bundles `libx264`/`libx265` GPL-2.0+ dylibs under BSD-3 metadata) and **never** on `imageio-ffmpeg` (bundles an `--enable-gpl` binary). ffmpeg is *shelled out to*, never linked.
+- **The licence tier is a refusal, not a warning**, and it is the default ceiling. `Look.max_tier` defaults to "shells out to a copyleft binary is fine"; a restricted-tier effect **raises** unless explicitly opted into. Same rule the video_gen group states for the falaw licence ledger: unknown is a refusal.
+- **Keep two things out** or this becomes a second muvid:
+  - **Execution and muxing.** muvid's `assemble.py` owns a bounded-memory invariant won after 30-cut OOM kills. A convenience `looks.render(clip, look)` *will* get used and *will* rebuild one big `-filter_complex`.
+  - **Cut/EDL decisions.** An `Effect.at` says *where a look applies*, never *where a cut is*.
+- Follow the house style: functional over OOP, dataclasses for data, `Protocol` over ABC, keyword-only past the 3rd argument, no magic numbers, module docstring on every module.
+
+## Validated starting material — a real look, already built
+
+The Que Calor V2 stylizer works and is in `~/Downloads/que_calor/work/style/` (see that folder's `README.md` and `LEDGER.md`). It is the first real customer and should become an example. What it established, all measured:
+
+- **The chain that works:** flatten (`cv2.pyrMeanShiftFiltering`) → 3D LUT (`lut3d`) → posterise. Frame-independent by construction — no temporal state, one fixed LUT — so it **cannot flicker**. Measured frame-to-frame change was 0.89–1.12× the source's own.
+- **`pyrMeanShiftFiltering`, never `edgePreservingFilter`.** The latter smooths *across* object boundaries and dissolves figures into the background. Mean-shift clusters in colour *and* position, so boundaries survive. This is the difference between a stylised look and the mushy-edges artefact.
+- **A gradient-map LUT is the right vehicle when the target's hue tracks its lightness.** Measure the target before assuming a filter. The reference here had **no black, no white and no outlines** — so the classic "cartoonify" (bilateral + adaptive-threshold black edges) would have been exactly wrong.
+- **The flattening scale must be per-source, and this is the subtle one.** The downscale/upscale round trip — not the filter's colour radius — governs retained sharpness (measured post-LUT: ~150 at full res, ~85 at 0.75, ~44 at 0.5; the radius barely moves it). A single global setting made the *softest* source softer still, so it became the mushiest thing on screen. **The right auto-rule normalises the OUTPUT across sources, not the input** — don't "sharpen the soft one"; measure post-effect sharpness per source and pick parameters that land them in family. Full detail in the muvid#63 comment.
+
+That last point is the strongest argument for the design: an `Effect`'s parameters must resolve against *the clip they apply to*, not be fixed at the top of a `Look`.
+
+## Refactor out of `mixing`, in this order
+
+1. `mixing/video/video_util.py` entire — `SOCIAL_SIZES`, `resize_to_dimensions` (stretch/fit/fill/social), `normalize_video_dimensions`, plus the duplicated centre-crop in `thumbnail.py`. This is the geometry tier.
+2. The six transitions in `video_concat.py` (`crossfade_transition` et al).
+
+Do this as a *deprecation-free* move — the group's prime directive is clean shape over backward compatibility, and mixing has no external users for these.
+
+---
+
+# How to run this session
+
+## 1. Set up the project with `wads` — do this first
+
+Use the `wads` scaffolding, not a hand-rolled `pyproject.toml`:
+
+```bash
+python -c "from wads.populate import populate_pkg_dir; populate_pkg_dir('$PP/t/looks', description='A facade over video stylization: named effects with licence tiers', root_url='https://github.com/thorwhalen')"
+```
+
+Read `~/.claude/skills/python-project-structure/SKILL.md` and the `wads-migrate` skill first. The CI is driven entirely by `[tool.wads.ci]` in `pyproject.toml`.
+
+## 2. Claim the name on PyPI immediately, at 0.0.0
+
+**Before writing real code.** `looks` was verified free on 2026-09-02, but a name is only yours once published. Publish a stub at version `0.0.0`, confirm it appears, and only then invest.
+
+```bash
+gh repo create thorwhalen/looks --public --source=. --remote=origin
+priv git_ops set-repo-secrets thorwhalen/looks   # ← BEFORE the first push, or CI 403s on publish
+git add -A && git commit -m "looks: scaffolding" && git push -u origin main
+```
+
+**`priv git_ops set-repo-secrets thorwhalen/looks` must run before you push.** A repo without `PYPI_PASSWORD` fails the publish step with a 403 and you discover it after the fact — this has bitten several packages in this fleet.
+
+Then watch it: `gh run watch` / `gh run list -R thorwhalen/looks`. Confirm `pip index versions looks` (or the PyPI JSON API) shows 0.0.0 before continuing.
+
+## 3. Then: as soon as anything works, push and let CI publish
+
+Don't batch. The point of steps 2–3 is to prove the whole path — name, secrets, CI, PyPI — while the package is trivial and a failure costs nothing. A merge to the default branch publishes.
+
+## 4. Research before designing
+
+**Search what already exists first**, with `ir` (the local agentic retrieval substrate — load its `ir-search` skill). Search the local ecosystem *and* your own past sessions: this fleet has a lot of prior art on ffmpeg filter chains, colour handling and registries, and `muvid.visualize` is only the most obvious piece.
+
+Then **trigger your own research** into `docs/`, and use it to plan. Concretely:
+
+- Put every research output in `docs/` as a dated, referenced note. Version-anchor claims about fast-moving dependencies — an unanchored finding about a library is a future bug.
+- Fan out agents on the questions that actually branch the design. Good candidates: what the effect-spec type should be (survey `falaw.Plan`, `an`'s `VisualPlan`, `burns.BurnsPath`); what the licence tiers should be and how each backend maps onto them; whether the GLSL/shader path is worth a backend; what the state of neural restyling is *with commercially-usable licences* (note AnimeGANv2 and White-box Cartoonization are both non-commercial — that killed the obvious route here).
+- **Give agents the measured facts above** rather than letting them rediscover them. They cost real time to establish.
+
+## 5. Land things
+
+Branch → PR → CI green → squash-merge → back to main. Merging publishes; that's intended.
+
+---
+
+## Open questions for the owner
+
+- **Should `burns` become a `looks` backend, or stay separate?** `burns.BurnsPath.evaluate(t) -> Rect` already *is* a pan/zoom spec, render-agnostic and JSON-serialisable, and `burns/backends.py`'s docstring names an ffmpeg fast-path as its intended second backend. There is a real argument that geometry-over-time belongs in `burns` and only *pixel* effects belong here. Decide before writing a second geometry type.
+- **Does `looks` own normalisation as well as stylization?** The Que Calor edit needed both — a measured per-clip continuity grade *and* an extreme look. They compile to the same `vf` insertion point. Treating them as one vocabulary is tempting and probably right, but say so deliberately.

looks-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thorwhalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

looks-0.0.1/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.5
+Name: looks
+Version: 0.0.1
+Summary: A facade over video stylization: named effects with licence tiers
+Project-URL: Homepage, https://github.com/thorwhalen/looks
+Project-URL: Repository, https://github.com/thorwhalen/looks
+Project-URL: Documentation, https://thorwhalen.github.io/looks
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# looks
+
+A facade over video stylization: named effects that compile to a backend command, each carrying a **licence tier** so a caller can demand commercial-safe-only and get a refusal rather than a surprise.
+
+Under construction — see `KICKOFF.md`.

looks-0.0.1/README.md

@@ -0,0 +1,5 @@
+# looks
+
+A facade over video stylization: named effects that compile to a backend command, each carrying a **licence tier** so a caller can demand commercial-safe-only and get a refusal rather than a surprise.
+
+Under construction — see `KICKOFF.md`.

looks-0.0.1/looks/__init__.py

@@ -0,0 +1,6 @@
+"""A facade over video stylization: named effects carrying a licence tier.
+
+Placeholder for the 0.0.0 name-claiming release. The real surface lands next.
+"""
+
+__version__ = "0.0.0"

looks-0.0.1/looks/tests/__init__.py

@@ -0,0 +1,3 @@
+"""Tests for :mod:`looks`. They live inside the package because CI runs
+``pytest --doctest-modules looks`` — a repo-root ``tests/`` is never collected.
+"""

looks-0.0.1/looks/tests/test_smoke.py

@@ -0,0 +1,7 @@
+"""The one test the 0.0.0 release needs: the package imports."""
+
+
+def test_import():
+    import looks
+
+    assert looks.__version__

looks-0.0.1/pyproject.toml

@@ -0,0 +1,156 @@
+[build-system]
+requires = [
+    "hatchling",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "looks"
+version = "0.0.1"
+description = "A facade over video stylization: named effects with licence tiers"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = []
+authors = []
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+
+
+[project.urls]
+Homepage = "https://github.com/thorwhalen/looks"
+Repository = "https://github.com/thorwhalen/looks"
+Documentation = "https://thorwhalen.github.io/looks"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+]
+docs = [
+    "sphinx>=6.0",
+    "sphinx-rtd-theme>=1.0",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+exclude = [
+    "**/*.ipynb",
+    ".git",
+    ".venv",
+    "build",
+    "dist",
+    "tests",
+    "examples",
+    "scrap",
+]
+
+[tool.ruff.lint]
+select = [
+    "D100",
+]
+ignore = [
+    "D203",
+    "E501",
+    "B905",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"**/tests/*" = [
+    "D",
+]
+"**/examples/*" = [
+    "D",
+]
+"**/scrap/*" = [
+    "D",
+]
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+testpaths = [
+    "looks",
+]
+doctest_optionflags = [
+    "ELLIPSIS",
+    "IGNORE_EXCEPTION_DETAIL",
+]
+addopts = "--doctest-modules"
+
+[tool.wads.ci]
+project_name = ""
+
+[tool.wads.ci.commands]
+pre_test = []
+test = []
+post_test = []
+lint = []
+format = []
+
+[tool.wads.ci.env]
+required_envvars = []
+test_envvars = []
+extra_envvars = []
+
+[tool.wads.ci.env.defaults]
+
+[tool.wads.ci.quality.ruff]
+enabled = true
+
+[tool.wads.ci.quality.black]
+enabled = false
+
+[tool.wads.ci.quality.mypy]
+enabled = false
+
+[tool.wads.ci.testing]
+enabled = true
+python_versions = [
+    "3.10",
+    "3.12",
+]
+pytest_args = [
+    "-v",
+    "--tb=short",
+]
+coverage_enabled = true
+coverage_threshold = 0
+coverage_report_format = [
+    "term",
+    "xml",
+]
+exclude_paths = [
+    "examples",
+    "scrap",
+]
+test_on_windows = true
+
+[tool.wads.ci.metrics]
+enabled = true
+config_path = ".github/umpyre-config.yml"
+storage_branch = "code-metrics"
+python_version = "3.10"
+force_run = false
+
+[tool.wads.ci.build]
+sdist = true
+wheel = true
+
+[tool.wads.ci.publish]
+enabled = true
+skip_ci_marker = "[skip ci]"
+publish_marker = "[publish]"
+
+[tool.wads.ci.docs]
+enabled = true
+builder = "epythet"
+ignore_paths = [
+    "tests/",
+    "scrap/",
+    "examples/",
+]