xevol 0.17.0 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xevol",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Xevol is a tool to consume, remix, make, publish, and offer systems, products, and workflows.",
   "type": "module",
   "bin": {

package/starters/blank/README.md

@@ -0,0 +1,12 @@
+# Starter film
+
+A 9-second code-drawn film: a title, three points, an end card, and a soundtrack mixed in the cloud.
+
+    xevol film render . --brand <brand> --draft --wait     # a cheap review cut
+    xevol film render . --brand <brand> --wait             # a final, with text and master checks
+    xevol film render . --brand <brand> --format wide --wait   # 1920x1080
+
+Edit `COPY`, the colours and `T` in `film.html`. Keep `window.DUR`, render.json `"duration"` and `DUR` in
+`scripts/mix.py` equal. For a voice-over, make one with Xevol's `make_voice`, download it to `assets/vo.wav` and set
+`V` in `scripts/mix.py`. Read `xevol film skill` for the craft rules. Font: Onest, SIL Open Font License
+(`assets/fonts/OFL-Onest.txt`).

package/starters/blank/assets/fonts/OFL-Onest.txt

@@ -0,0 +1,93 @@
+Copyright 2021 The Onest Project Authors (https://github.com/simpals/onest)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/starters/blank/film.html

@@ -1,8 +1,101 @@
 <!doctype html>
+<html lang="en">
+<head>
 <meta charset="utf-8">
-<title>Synthetic code film</title>
+<title>Starter film</title>
+<style>
+@font-face { font-family: Onest; src: url(assets/fonts/onest-latin.woff2) format('woff2'); font-weight: 100 900;
+  unicode-range: U+0000-00FF, U+2013-2014, U+2018-201E, U+2026; }
+@font-face { font-family: Onest; src: url(assets/fonts/onest-cyrillic-wght-normal.woff2) format('woff2'); font-weight: 100 900;
+  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116; }
+html, body { margin: 0; background: #111; }
+canvas { display: block; }
+</style>
+</head>
+<body>
+<canvas id="frame"></canvas>
 <script>
-  // A fixture, not a real film: the page contract without any company content.
-  window.DUR = 2;
-  window.seek = () => {};
+// A starter code film: a title, three points that appear one by one, and an end card. Replace COPY, the colours
+// and the times; keep the contract: frame t is drawn from t alone (no clocks, no Math.random, no network),
+// window.DUR matches render.json "duration", window.ready resolves when fonts are loaded, window.seek(t) draws.
+// window.CUES lists the picture's sound moments; scripts/mix.py turns them into the soundtrack in the cloud.
+// Tall (1080x1920) by default; `xevol film render . --format wide` renders 1920x1080 (?shape=16x9).
+const WIDE = new URLSearchParams(location.search).get('shape') === '16x9';
+const W = WIDE ? 1920 : 1080, H = WIDE ? 1080 : 1920, DUR = 9;
+const ACCENT = '#5bc0eb', INK = '#111111', WHITE = '#ffffff', GREY = '#a7a7a7';
+const COPY = {
+  title: 'Say one thing.',
+  sub: 'Then show how.',
+  points: ['First, the problem', 'Then, what changes', 'Last, the result'],
+  end: 'example.com',
+};
+// When each part appears, in seconds. Text needs about 1 s per short line to be read.
+const T = { title: 0, sub: 1.0, points: [3.0, 4.2, 5.4], end: 7.2 };
+const CUES = [
+  {t: T.title, kind: 'swell'},
+  ...T.points.map(t => ({t, kind: 'tick'})),
+  {t: T.end, kind: 'chime'},
+];
+window.CUES = CUES; window.DUR = DUR;
+
+const clamp = (x, a = 0, b = 1) => Math.min(b, Math.max(a, x));
+const eOut = k => 1 - Math.pow(1 - clamp(k), 3);
+const at = (t, a, d = 0.45) => clamp((t - a) / d);
+
+const c = document.getElementById('frame');
+c.width = W; c.height = H;
+const G = c.getContext('2d');
+
+function text(s, x, y, size, color, {weight = 700, align = 'left', alpha = 1, rise = 0} = {}) {
+  if (alpha <= 0) return;
+  G.save();
+  G.globalAlpha = alpha;
+  G.font = `${weight} ${size}px Onest`;
+  G.letterSpacing = `${(size >= 100 ? -0.03 : -0.01) * size}px`;
+  G.fillStyle = color; G.textAlign = align; G.textBaseline = 'alphabetic';
+  G.fillText(s, x, y + rise);
+  G.restore();
+}
+
+function draw(t) {
+  G.fillStyle = INK; G.fillRect(0, 0, W, H);
+  // A slow glow that never stops moving: a held, perfectly still frame reads as a frozen video (master-audit).
+  const gy = H * (0.85 - 0.35 * t / DUR), gx = W * (0.35 + 0.3 * t / DUR);
+  const glow = G.createRadialGradient(gx, gy, 0, gx, gy, Math.max(W, H) * 0.55);
+  glow.addColorStop(0, 'rgba(91,192,235,0.16)'); glow.addColorStop(1, 'rgba(91,192,235,0)');
+  G.fillStyle = glow; G.fillRect(0, 0, W, H);
+  const x = WIDE ? 160 : 90, s = WIDE ? 0.9 : 1;
+
+  // Title, then it fades out as the points arrive (fade, do not fly: fast text cannot be read).
+  const titleOut = eOut(at(t, 2.5, 0.4));
+  const a = eOut(at(t, T.title)) * (1 - titleOut);
+  text(COPY.title, x, H * 0.45, 120 * s, WHITE, {weight: 800, alpha: a, rise: (1 - eOut(at(t, T.title))) * 30});
+  text(COPY.sub, x, H * 0.45 + 110 * s, 70 * s, ACCENT, {weight: 600, alpha: eOut(at(t, T.sub)) * (1 - titleOut)});
+
+  // Three points, each lit when it arrives and dimmed when the next one does.
+  const pointsOut = eOut(at(t, T.end - 0.3, 0.4));
+  COPY.points.forEach((p, i) => {
+    const k = eOut(at(t, T.points[i]));
+    const next = i < 2 ? eOut(at(t, T.points[i + 1], 0.35)) : 0;
+    const y = H * 0.36 + i * 160 * s;
+    G.save(); G.globalAlpha = k * (1 - 0.55 * next) * (1 - pointsOut);
+    G.fillStyle = ACCENT; G.fillRect(x, y - 54 * s, 12 * s, 64 * s); G.restore();
+    text(p, x + 44 * s, y, 66 * s, WHITE, {weight: 700, alpha: k * (1 - 0.55 * next) * (1 - pointsOut), rise: (1 - k) * 24});
+  });
+
+  // End card.
+  const e = eOut(at(t, T.end));
+  text(COPY.end, W / 2, H * 0.5, 92 * s, WHITE, {weight: 800, align: 'center', alpha: e, rise: (1 - e) * 24});
+  G.save(); G.globalAlpha = e; G.fillStyle = ACCENT;
+  G.fillRect(W / 2 - 220 * s * e, H * 0.5 + 40 * s, 440 * s * e, 10 * s); G.restore();
+  text('Made with xevol film', W / 2, H * 0.5 + 140 * s, 40 * s, GREY, {weight: 500, align: 'center', alpha: eOut(at(t, T.end + 0.4))});
+}
+
+window.seek = t => draw(Math.max(0, Math.min(DUR, t)));
+window.ready = (async () => {
+  for (const w of [500, 600, 700, 800]) await document.fonts.load(`${w} 100px Onest`, 'Say one thing.');
+  draw(0);
+})();
 </script>
+</body>
+</html>

package/starters/blank/render.json

@@ -1,26 +1,5 @@
-{
-	"width": 1080,
-	"height": 1920,
-	"fps": 30,
-	"sub": 2,
-	"shutter": 180,
-	"query": { "shape": "9x16" },
-	"out": "out/9x16",
-	"bundle": ["film.html", "assets/**"],
-	"audio": "out/audio.wav",
-	"finish": ["scripts/finish.py", "9x16"],
-	"duration": 2,
-	"formats": {
-		"tall": {
-			"width": 1920,
-			"height": 1080,
-			"out": "out/16x9",
-			"query": { "shape": "16x9" },
-			"finish": ["scripts/finish.py", "16x9"]
-		},
-		"localized": {
-			"out": "out/{lang}",
-			"finish": ["scripts/finish.py", "9x16", "{lang}.json"]
-		}
-	}
-}
+{"width": 1080, "height": 1920, "fps": 30, "sub": 4, "shutter": 180, "duration": 9,
+ "out": "out/9x16",
+ "bundle": ["film.html", "assets/**"],
+ "mix": {"cues": ["--out", "out"], "run": ["scripts/mix.py"], "out": "out/audio.wav"},
+ "formats": {"wide": {"width": 1920, "height": 1080, "out": "out/16x9", "query": {"shape": "16x9"}}}}

package/starters/blank/scripts/mix.py

@@ -0,0 +1,121 @@
+"""The starter film's soundtrack, made in the cloud (render.json "mix"): xevol film render runs it, not you.
+
+    render.mjs . --cues --out out      -> out/cues.json (the picture's window.CUES)
+    python -I scripts/mix.py           -> out/audio.wav, 48 kHz stereo, DUR seconds, about -16 LUFS / -2 dBTP
+
+Optional voice-over: put a 48 kHz 16-bit WAV at assets/vo.wav (download one made by Xevol's make_voice) and set V
+to when it starts; the bed ducks under it. Without it the film has music and cue sounds only. One synthesized sound
+per cue kind in SOUNDS. numpy and ffmpeg only; no network. Keep DUR equal to render.json "duration".
+"""
+import json
+import os
+import subprocess
+import sys
+import wave
+from pathlib import Path
+
+import numpy as np
+
+ROOT = Path(os.environ.get('FILM_ROOT') or Path(__file__).resolve().parent.parent)
+OUT = ROOT / 'out'
+SR, DUR, V = 48000, 9.0, 0.4
+N = int(DUR * SR)
+t_all = np.arange(N) / SR
+
+
+def read_voice():
+    with wave.open(str(ROOT / 'assets/vo.wav'), 'rb') as w:
+        assert w.getframerate() == SR and w.getsampwidth() == 2, 'vo.wav must be 48 kHz 16-bit'
+        y = np.frombuffer(w.readframes(w.getnframes()), np.int16).astype(np.float32) / 32768
+        return y.reshape(-1, w.getnchannels()).mean(axis=1)
+
+
+def env(n, attack, release):
+    e = np.ones(n, np.float32)
+    a, r = int(attack * SR), int(release * SR)
+    e[:a] = np.linspace(0, 1, a) if a else 1
+    e[n - r:] *= np.linspace(1, 0, r) ** 2 if r else 1
+    return e
+
+
+def tone(freqs, seconds, decay, level):
+    n = int(seconds * SR)
+    t = np.arange(n) / SR
+    y = sum(np.sin(2 * np.pi * f * t) * (0.6 ** i) for i, f in enumerate(freqs))
+    return (y * np.exp(-t / decay) * env(n, 0.004, 0.05) * level).astype(np.float32)
+
+
+def noise_swell(seconds, level):
+    n = int(seconds * SR)
+    rng = np.random.default_rng(7)                          # fixed seed: the same mix every time
+    y = rng.standard_normal(n).astype(np.float32)
+    k = np.exp(-np.arange(256) / 40); k /= k.sum()
+    y = np.convolve(y, k, 'same')                           # soften the hiss
+    shape = np.sin(np.linspace(0, np.pi, n)) ** 2
+    return (y * shape * level).astype(np.float32)
+
+
+SOUNDS = {
+    'swell': lambda: noise_swell(1.2, 0.05),
+    'tick': lambda: tone([1318.5, 2637], 0.35, 0.07, 0.16),     # E6, a pluck per lesson part
+    'whoosh': lambda: noise_swell(0.7, 0.08),
+    'chime': lambda: tone([1760, 2637, 3520], 1.6, 0.45, 0.14),
+    'pop': lambda: tone([880, 1760], 0.25, 0.05, 0.14),
+}
+
+
+def bed():
+    # D major, warm and slow: Dmaj7, Bm7, Gmaj7, A, three seconds each, sines with a slow fade between chords.
+    chords = [[146.83, 220.0, 277.18, 369.99], [123.47, 185.0, 220.0, 293.66],
+              [98.0, 146.83, 246.94, 293.66]]
+    y = np.zeros(N, np.float32)
+    for i, chord in enumerate(chords):
+        a, b = int(i * 3.0 * SR), int(min(DUR, i * 3.0 + 3.6) * SR)
+        t = np.arange(b - a) / SR
+        part = sum(np.sin(2 * np.pi * f * t) + 0.5 * np.sin(2 * np.pi * f * 1.003 * t) for f in chord)
+        y[a:b] += part * env(b - a, 0.8, 0.9) * 0.022
+    y[-int(1.2 * SR):] *= np.linspace(1, 0, int(1.2 * SR)) ** 2   # the film fades out
+    return y
+
+
+def main():
+    cues = json.loads((OUT / 'cues.json').read_text())['cues']
+    voice = np.zeros(N, np.float32)
+    if (ROOT / 'assets/vo.wav').exists():
+        vo = read_voice()
+        a = int(V * SR)
+        voice[a:a + len(vo)] = vo[:N - a]
+
+    # Duck the bed by 7 dB wherever the voice is speaking (a 150 ms envelope follower).
+    k = np.ones(int(0.15 * SR), np.float32) / int(0.15 * SR)
+    level = np.convolve(np.abs(voice), k, 'same')
+    duck = 1 - (1 - 10 ** (-7 / 20)) * np.clip(level / 0.02, 0, 1)
+    music = bed() * duck
+
+    fx = np.zeros(N, np.float32)
+    for cue in cues:
+        s = SOUNDS[cue['kind']]()
+        start = int(float(cue['t']) * SR) - (len(s) // 2 if cue['kind'] in ('swell', 'whoosh') else 0)
+        start = max(0, start)
+        fx[start:start + len(s)] += s[:N - start]
+
+    left = voice + music + fx
+    right = voice + music * 0.97 + fx
+    mix = np.stack([left, right], axis=1)
+    raw = OUT / 'mix-raw.wav'
+    with wave.open(str(raw), 'wb') as w:
+        w.setnchannels(2); w.setsampwidth(2); w.setframerate(SR)
+        w.writeframes((np.clip(mix, -1, 1) * 32767).astype(np.int16).tobytes())
+    # Loudness to the craft target, then exactly 12.000 s at 48 kHz stereo.
+    r = subprocess.run(['ffmpeg', '-v', 'error', '-y', '-i', str(raw), '-af',
+                        f'loudnorm=I=-16:TP=-2:LRA=11,aresample={SR},apad,atrim=0:{DUR}',
+                        '-ar', str(SR), '-ac', '2', '-c:a', 'pcm_s16le', str(OUT / 'audio.wav')],
+                       capture_output=True, text=True)
+    if r.returncode:
+        sys.exit(f'mix.py: ffmpeg failed: {r.stderr[-800:]}')
+    raw.unlink()
+    print(f'out/audio.wav: {len(cues)} cues, bed in D, voice {"at " + str(V) + " s" if voice.any() else "none"}, loudnorm -16 LUFS')
+
+
+if __name__ == '__main__':
+    main()

package/starters/blank/assets/fonts/TestSans.woff2

@@ -1 +0,0 @@
-synthetic font placeholder

package/starters/blank/assets/plate.txt

@@ -1 +0,0 @@
-synthetic plate

package/starters/blank/notes.txt

@@ -1 +0,0 @@
-not declared in render.json

package/starters/blank/out/audio.wav

@@ -1 +0,0 @@
-RIFFsynthetic-wav

package/starters/blank/scripts/finish.py

@@ -1 +0,0 @@
-print("synthetic finish")