Skip to content

Commit 47cf338

Browse files
committed
TL10: in progress: what the frame store decides, in sdk/timeline cache.ts
changed(before, after): the frames whose picture or sound differ between two states, by what is drawn over each frame (a clip moved gives its old span and its new one; a split of footage gives none; a name, a lock or a marker gives none). keyOf: what a kept range is kept under, the same for two states that draw it the same, so an undo finds its frames again. evict: a closed version's frames first, then the least recently played, never what is under the playhead while anything else can go. ahead: what to draw next, from the playhead on. 44 tests. The stage that draws and the store that holds frames aren't built.
1 parent b2a52f6 commit 47cf338

3 files changed

Lines changed: 192 additions & 0 deletions

File tree

‎sdk/timeline/src/cache.ts‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
// The frames kept while editing (docs/timeline.feature TL10): which ranges an edit changed (so only those are drawn
2+
// again, TL10c), what a kept range is kept under (TL10b), and what goes first when the store is over its size
3+
// (TL10e). Pure: the stage that draws frames and the store that holds them use these to decide.
4+
import { type Clip, end, type Frames, type Timeline, type Track } from "./model"
5+
6+
export type Range = [from: Frames, to: Frames]
7+
8+
/** Ranges in order, touching and overlapping ones joined, empty ones dropped. */
9+
export function joined(ranges: Range[]): Range[] {
10+
const out: Range[] = []
11+
for (const [a, b] of [...ranges].filter(([a, b]) => b > a).sort((x, y) => x[0] - y[0])) {
12+
const last = out[out.length - 1]
13+
if (last && a <= last[1]) last[1] = Math.max(last[1], b)
14+
else out.push([a, b])
15+
}
16+
return out
17+
}
18+
19+
/** `ranges` with `cut` taken out of them. */
20+
export function without(ranges: Range[], cut: Range[]): Range[] {
21+
let out = joined(ranges)
22+
for (const [c0, c1] of joined(cut)) out = out.flatMap(([a, b]): Range[] => (c1 <= a || c0 >= b ? [[a, b]] : [[a, Math.min(b, c0)], [Math.max(a, c1), b]])).filter(([a, b]) => b > a)
23+
return out
24+
}
25+
26+
const drawn = (k: Track, c: Clip) => !c.off && !(k.kind === "sound" ? k.muted : k.hidden)
27+
/** What a clip draws, said so that the same pictures give the same words wherever the clip is cut: a media clip
28+
* by where its source sits against the timeline (so the two halves of a split say what the whole did), anything
29+
* else by where it starts (its content runs from its own first frame). Keys and fades are said at their timeline
30+
* frames. Its name, its lock and its group aren't in it. */
31+
function look(k: Track, n: number, c: Clip): string {
32+
const still = c.in !== undefined && !c.curve
33+
const phase = still ? `p${c.in! - c.start * (c.speed && c.speed > 0 ? c.speed : 1)}` : `s${c.start}+${c.length}`
34+
const keys = Object.entries(c.keys ?? {}).map(([p, ks]) => [p, ks.map((x) => [x.at + c.start, x.value, x.ease ?? "linear"])])
35+
const fades = [c.fadeIn ? [c.start, c.fadeIn] : 0, c.fadeOut ? [end(c), c.fadeOut] : 0]
36+
return JSON.stringify([n, k.kind, c.kind, phase, c.speed ?? 1, c.curve ?? null, c.shows ?? null, c.props ?? null, keys, c.volume ?? 1, fades, c.at ?? null])
37+
}
38+
39+
/** Every drawn thing on the timeline as the span it covers and what it draws there. */
40+
function spans(t: Timeline): { span: Range; look: string }[] {
41+
const out: { span: Range; look: string }[] = []
42+
t.tracks.forEach((k, n) => {
43+
for (const c of k.clips) if (drawn(k, c)) out.push({ span: [c.start, end(c)], look: look(k, n, c) })
44+
})
45+
for (const x of t.transitions) {
46+
const c = t.tracks.flatMap((k) => k.clips).find((o) => o.id === x.after)
47+
const half = Math.ceil(x.length / 2)
48+
if (c) out.push({ span: [end(c) - half, end(c) + half], look: `x:${x.kind}:${x.length}:${end(c)}` })
49+
}
50+
return out
51+
}
52+
53+
/** The frames whose picture or sound differ between two states of a timeline: wherever what is drawn over a frame
54+
* isn't what was. Moving a clip from 2:00-2:05 to 2:10-2:15 gives those two ranges and nothing else (TL10c); a
55+
* split of footage gives none. */
56+
export function changed(before: Timeline, after: Timeline): Range[] {
57+
const a = spans(before), b = spans(after)
58+
const edges = [...new Set([...a, ...b].flatMap((x) => x.span))].sort((x, y) => x - y)
59+
const over = (xs: { span: Range; look: string }[], from: Frames, to: Frames) => xs.filter((x) => x.span[0] < to && x.span[1] > from).map((x) => x.look).sort().join("\n")
60+
const out: Range[] = []
61+
for (let i = 0; i + 1 < edges.length; i++) if (over(a, edges[i], edges[i + 1]) !== over(b, edges[i], edges[i + 1])) out.push([edges[i], edges[i + 1]])
62+
return joined(out)
63+
}
64+
65+
/** What a range of kept frames is kept under: everything that draws it. Two states of a timeline that draw the
66+
* range the same give the same key, so frames drawn before an edit elsewhere (or before an undo) are found again. */
67+
export function keyOf(t: Timeline, [from, to]: Range, media: (clip: Clip) => string = () => ""): string {
68+
const parts: string[] = [`${t.fps}`]
69+
t.tracks.forEach((k, n) => {
70+
for (const c of k.clips) if (drawn(k, c) && c.start < to && end(c) > from) parts.push(`${look(k, n, c)}:${media(c)}`)
71+
})
72+
for (const x of spans(t)) if (x.look.startsWith("x:") && x.span[0] < to && x.span[1] > from) parts.push(x.look)
73+
// FNV-1a over the parts: a short name for a file, not a secret
74+
let h = 0x811c9dc5
75+
for (const ch of parts.sort().join("|")) h = Math.imul(h ^ ch.charCodeAt(0), 0x01000193) >>> 0
76+
return `${from}-${to}-${h.toString(16).padStart(8, "0")}`
77+
}
78+
79+
export interface Kept {
80+
key: string
81+
bytes: number
82+
/** when it was last played (ms) */
83+
used: number
84+
/** it belongs to a version that was closed or discarded: it goes at once */
85+
stale?: boolean
86+
}
87+
88+
/** The keys to drop so the store is at most `limit` bytes: stale ones first, then the least recently played. What
89+
* is under the playhead (`hold`) stays while anything else can go (TL10e). */
90+
export function evict(kept: Kept[], limit: number, hold: Set<string> = new Set()): string[] {
91+
let total = kept.reduce((n, k) => n + k.bytes, 0)
92+
const out: string[] = []
93+
const order = [...kept].sort((a, b) => Number(!!b.stale) - Number(!!a.stale) || Number(hold.has(a.key)) - Number(hold.has(b.key)) || a.used - b.used)
94+
for (const k of order) {
95+
if (!k.stale && total <= limit) break
96+
out.push(k.key)
97+
total -= k.bytes
98+
}
99+
return out
100+
}
101+
102+
/** The ranges to draw next while there is time (TL10d): what isn't kept from the playhead on, nearest first, each
103+
* at most `chunk` frames, then what is before it. */
104+
export function ahead(length: Frames, kept: Range[], playhead: Frames, chunk: Frames): Range[] {
105+
const missing = without([[0, length]], kept)
106+
const pieces = missing.flatMap(([a, b]): Range[] => Array.from({ length: Math.ceil((b - a) / chunk) }, (_, i) => [a + i * chunk, Math.min(b, a + (i + 1) * chunk)] as Range))
107+
const after = pieces.filter(([, b]) => b > playhead).sort((x, y) => x[0] - y[0])
108+
const before = pieces.filter(([, b]) => b <= playhead).sort((x, y) => y[0] - x[0])
109+
return [...after, ...before]
110+
}

‎sdk/timeline/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ export * from "./keys"
66
export * from "./speed"
77
export * from "./snap"
88
export * from "./read"
9+
export * from "./cache"

‎sdk/timeline/test/cache.test.ts‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
import { describe, expect, test } from "bun:test"
2+
import { ahead, apply, changed, type Clip, empty, evict, joined, keyOf, type Timeline, without } from "../src"
3+
4+
const clip = (id: string, start: number, len: number, more: Partial<Clip> = {}): Clip => ({ id, kind: "video", start, length: len, ...more })
5+
const film = (): Timeline => ({
6+
...empty(30),
7+
magnet: false,
8+
tracks: [
9+
{ id: "overlay-1", kind: "overlay", clips: [clip("logo", 3600, 150)] },
10+
{ id: "main", kind: "main", clips: [clip("a", 0, 3000), clip("b", 3000, 3000)] },
11+
{ id: "sound-1", kind: "sound", clips: [clip("music", 0, 6000, { kind: "audio" })] },
12+
],
13+
})
14+
const done = (t: Timeline, op: Parameters<typeof apply>[1]) => {
15+
const r = apply(t, op)
16+
if (!r.ok) throw new Error(r.why)
17+
return r.timeline
18+
}
19+
20+
describe("TL10c: an edit drops only what it changed", () => {
21+
test("a clip moved from 2:00-2:05 to 2:10-2:15 changes those two ranges and nothing else", () => {
22+
const t = film()
23+
expect(changed(t, done(t, { op: "move", ids: ["logo"], by: 300 }))).toEqual([[3600, 3750], [3900, 4050]])
24+
})
25+
26+
test("a key, a hidden track and a transition change the spans they draw; a name, a lock and a marker change nothing", () => {
27+
const t = film()
28+
expect(changed(t, done(t, { op: "key", id: "logo", prop: "scale", at: 10, value: 2 }))).toEqual([[3600, 3750]])
29+
expect(changed(t, done(t, { op: "track", id: "overlay-1", set: { hidden: true } }))).toEqual([[3600, 3750]])
30+
expect(changed(t, done(t, { op: "track", id: "sound-1", set: { muted: true } }))).toEqual([[0, 6000]])
31+
expect(changed(t, done(t, { op: "transition", transition: { id: "x", kind: "dissolve", after: "a", length: 30 } }))).toEqual([[2985, 3015]])
32+
expect(changed(t, done(t, { op: "set", id: "a", set: { name: "Opening" } }))).toEqual([])
33+
expect(changed(t, done(t, { op: "track", id: "main", set: { locked: true, height: 80 } }))).toEqual([])
34+
expect(changed(t, done(t, { op: "mark", marker: { id: "m", at: 100 } }))).toEqual([])
35+
})
36+
37+
test("a split of footage draws the same frames: nothing is drawn again; a split of anything else restarts its right half", () => {
38+
const footage: Timeline = { ...film(), tracks: [{ id: "main", kind: "main", clips: [clip("a", 0, 3000, { in: 0, source: 9000 })] }] }
39+
expect(changed(footage, done(footage, { op: "split", at: 1000, ids: ["a"] }))).toEqual([])
40+
// and one half deleted changes only that half (the magnet off: the other stays put)
41+
const cut = done(done(footage, { op: "split", at: 1000, ids: ["a"] }), { op: "remove", ids: ["a"] })
42+
expect(changed(footage, cut)).toEqual([[0, 1000]])
43+
const t = film()
44+
expect(changed(t, done(t, { op: "split", at: 1000, ids: ["a"] }))).toEqual([[0, 3000]])
45+
})
46+
47+
test("a range's key is the same for two states that draw it the same, and differs when they don't", () => {
48+
const t = film()
49+
const moved = done(t, { op: "move", ids: ["logo"], by: 300 })
50+
expect(keyOf(moved, [0, 3000])).toBe(keyOf(t, [0, 3000]))
51+
expect(keyOf(moved, [3600, 3750])).not.toBe(keyOf(t, [3600, 3750]))
52+
// undone: the frames kept before the edit are found again
53+
expect(keyOf(done(moved, { op: "move", ids: ["logo"], by: -300 }), [3600, 3750])).toBe(keyOf(t, [3600, 3750]))
54+
// the same clip over other media is another picture
55+
expect(keyOf(t, [0, 3000], () => "v2")).not.toBe(keyOf(t, [0, 3000], () => "v1"))
56+
})
57+
})
58+
59+
describe("TL10d, TL10e: what is drawn next, and what goes first", () => {
60+
test("ranges join, and one taken out of another leaves the rest", () => {
61+
expect(joined([[10, 20], [0, 5], [5, 10], [30, 30], [18, 25]])).toEqual([[0, 25]])
62+
expect(without([[0, 100]], [[20, 30], [90, 120]])).toEqual([[0, 20], [30, 90]])
63+
})
64+
65+
test("from the playhead on first, nearest first, then what is behind it", () => {
66+
expect(ahead(300, [[100, 160]], 120, 60)).toEqual([[160, 220], [220, 280], [280, 300], [60, 100], [0, 60]])
67+
expect(ahead(300, [[0, 300]], 0, 60)).toEqual([])
68+
})
69+
70+
test("a closed version's frames go at once, then the least recently played, never what is under the playhead while anything else can go", () => {
71+
const kept = [
72+
{ key: "old", bytes: 40, used: 1 },
73+
{ key: "here", bytes: 40, used: 2 },
74+
{ key: "recent", bytes: 40, used: 9 },
75+
{ key: "closed", bytes: 10, used: 8, stale: true },
76+
]
77+
expect(evict(kept, 1000)).toEqual(["closed"])
78+
expect(evict(kept, 90, new Set(["here"]))).toEqual(["closed", "old"])
79+
expect(evict(kept, 30, new Set(["here"]))).toEqual(["closed", "old", "recent", "here"])
80+
})
81+
})

0 commit comments

Comments
 (0)