conformtools 0.6.5 → 0.6.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/README.md +18 -13
  2. package/dist/account-DJTD3KYK.js +3 -0
  3. package/dist/arriraw-YIJ3BYNN.js +525 -0
  4. package/dist/avid-panel/MANIFEST.json +11 -0
  5. package/dist/avid-panel/avid-manifest.json +46 -0
  6. package/dist/avid-panel/icon.svg +4 -0
  7. package/dist/avid-panel/icons/conformtools.svg +4 -0
  8. package/dist/avid-panel/index.html +26 -0
  9. package/dist/avid-panel/panel.css +12 -0
  10. package/dist/avid-panel/panel.js +7 -0
  11. package/dist/bridge-JQF4V3V2.js +3 -0
  12. package/dist/browser/timeline_core_bg.wasm +0 -0
  13. package/dist/chunk-2BPR6LK6.js +3 -0
  14. package/dist/chunk-3D3Z4TBR.js +3 -0
  15. package/dist/chunk-55BKURYP.js +378 -0
  16. package/dist/chunk-5WEZRGXG.js +39 -0
  17. package/dist/chunk-6V4OEOOX.js +3 -0
  18. package/dist/chunk-7D7H6VFW.js +3 -0
  19. package/dist/chunk-A7FNR3T5.js +3 -0
  20. package/dist/chunk-AACY2V3L.js +3 -0
  21. package/dist/chunk-AMRJXYL4.js +3 -0
  22. package/dist/chunk-C2ESM27Z.js +3 -0
  23. package/dist/chunk-D4WPRRBT.js +3 -0
  24. package/dist/chunk-D6YDLKSA.js +3 -0
  25. package/dist/chunk-DKGGJM6Z.js +3 -0
  26. package/dist/chunk-EUBXH67N.js +7 -0
  27. package/dist/chunk-GK4YYKJ6.js +19 -0
  28. package/dist/chunk-GM6QKY7W.js +3 -0
  29. package/dist/chunk-J2JXLEAI.js +3 -0
  30. package/dist/chunk-JV7TZDKJ.js +3 -0
  31. package/dist/chunk-NAFLOZER.js +9 -0
  32. package/dist/chunk-NFJHWZJX.js +3 -0
  33. package/dist/chunk-NU3X7P4N.js +3 -0
  34. package/dist/chunk-P2LL3JMC.js +20 -0
  35. package/dist/chunk-PFISREY4.js +3 -0
  36. package/dist/chunk-PFZVET7S.js +3 -0
  37. package/dist/chunk-PHAMF4JF.js +4 -0
  38. package/dist/chunk-PLRB2YXJ.js +3 -0
  39. package/dist/chunk-PSANHDZM.js +3 -0
  40. package/dist/chunk-RGMTLNMF.js +3 -0
  41. package/dist/chunk-RJ6JA2LZ.js +3 -0
  42. package/dist/chunk-S5JDS5PQ.js +5 -0
  43. package/dist/chunk-SGLQY53R.js +3 -0
  44. package/dist/chunk-SKFMOLUO.js +8 -0
  45. package/dist/chunk-SNTAZJ5A.js +6 -0
  46. package/dist/chunk-TK55FA56.js +3 -0
  47. package/dist/chunk-TXQR2HI2.js +4 -0
  48. package/dist/chunk-VIBEEWPC.js +10 -0
  49. package/dist/chunk-WN53ARHJ.js +3 -0
  50. package/dist/chunk-XLEINKFL.js +5 -0
  51. package/dist/claude-setup-IIWUB4CE.js +5 -0
  52. package/dist/cli.js +17 -0
  53. package/dist/clip-state-B6JOX3JE.js +3 -0
  54. package/dist/conformtools-analyze +0 -0
  55. package/dist/conformtools-decode +0 -0
  56. package/dist/cr3-wasm-HLJWEV2S.js +3 -0
  57. package/dist/dng-wasm-CQDLPM5V.js +3 -0
  58. package/dist/dpx-wasm-TLGMM7BO.js +3 -0
  59. package/dist/engine-P6H5P6HP.js +5 -0
  60. package/dist/esm-SFFBP7PS.js +3 -0
  61. package/dist/exr-wasm-2NPKPTVB.js +3 -0
  62. package/dist/flame/hook/conformtools_flame/__init__.py +10 -0
  63. package/dist/flame/hook/conformtools_flame/building.py +191 -0
  64. package/dist/flame/hook/conformtools_flame/hook.py +177 -0
  65. package/dist/flame/hook/conformtools_flame/render.py +622 -0
  66. package/dist/flame/hook/conformtools_flame/util.py +33 -0
  67. package/dist/flame/hook/conformtools_flame/verbs.py +1037 -0
  68. package/dist/flame/hook/conformtools_flame_hook.py +42 -0
  69. package/dist/fonts/gfx/BarlowCondensed-Bold.ttf +0 -0
  70. package/dist/fonts/gfx/BarlowCondensed-Regular.ttf +0 -0
  71. package/dist/fonts/gfx/InstrumentSerif-Regular.ttf +0 -0
  72. package/dist/fonts/gfx/Inter-Bold.ttf +0 -0
  73. package/dist/fonts/gfx/Inter-Regular.ttf +0 -0
  74. package/dist/fonts/gfx/JetBrainsMono-Bold.ttf +0 -0
  75. package/dist/fonts/gfx/JetBrainsMono-Regular.ttf +0 -0
  76. package/dist/fonts/gfx/OFL.txt +100 -0
  77. package/dist/framing-SWOD4CWB.js +3 -0
  78. package/dist/gfx-worker.js +3 -0
  79. package/dist/h264-JJMZSUWW.js +3 -0
  80. package/dist/h264-mxf-DCUOGLDU.js +3 -0
  81. package/dist/host-relink-TWAF6WIG.js +10 -0
  82. package/dist/hosts-Z666EF7V.js +3 -0
  83. package/dist/http.js +5 -0
  84. package/dist/i2o-transfer +0 -0
  85. package/dist/inspect-FJKYPEXL.js +68 -0
  86. package/dist/isobmff-VJOWP4MH.js +3 -0
  87. package/dist/mc-video-5MGGOQN4.js +3 -0
  88. package/dist/mcp.js +13 -0
  89. package/dist/media-NZYVREUF.js +3 -0
  90. package/dist/media_core-YZ3PABEG.js +9 -0
  91. package/dist/media_core_bg-FDL7GJZP.js +3 -0
  92. package/dist/media_core_bg-XRBVKQZH.js +3 -0
  93. package/dist/mxf-FJSRFLJC.js +3 -0
  94. package/dist/nuke/panel/python/Startup/conformtools_nuke_startup.py +44 -0
  95. package/dist/nuke/panel/python/conformtools_nuke/__init__.py +10 -0
  96. package/dist/nuke/panel/python/conformtools_nuke/panel.py +217 -0
  97. package/dist/nuke/panel/python/conformtools_nuke/verbs.py +837 -0
  98. package/dist/ops-X7NAREC4.js +3 -0
  99. package/dist/peer-kit/ctpeer/__init__.py +21 -0
  100. package/dist/peer-kit/ctpeer/client.py +247 -0
  101. package/dist/peer-kit/ctpeer/neutral.py +178 -0
  102. package/dist/peer-kit/ctpeer/pairing.py +139 -0
  103. package/dist/peer-kit/ctpeer/protocol.py +209 -0
  104. package/dist/peer-kit/ctpeer/websocket.py +289 -0
  105. package/dist/premiere-uxp/icons/panel.png +0 -0
  106. package/dist/premiere-uxp/icons/panel@2x.png +0 -0
  107. package/dist/premiere-uxp/icons/plugin.png +0 -0
  108. package/dist/premiere-uxp/icons/plugin@2x.png +0 -0
  109. package/dist/premiere-uxp/index.html +38 -0
  110. package/dist/premiere-uxp/index.js +93 -0
  111. package/dist/premiere-uxp/lib/clipmeta.js +170 -0
  112. package/dist/premiere-uxp/lib/ctx.js +68 -0
  113. package/dist/premiere-uxp/lib/edit.js +516 -0
  114. package/dist/premiere-uxp/lib/handles.js +57 -0
  115. package/dist/premiere-uxp/lib/markers.js +198 -0
  116. package/dist/premiere-uxp/lib/pairing.js +67 -0
  117. package/dist/premiere-uxp/lib/premiere.js +91 -0
  118. package/dist/premiere-uxp/lib/probe.js +452 -0
  119. package/dist/premiere-uxp/lib/protocol.js +165 -0
  120. package/dist/premiere-uxp/lib/render.js +45 -0
  121. package/dist/premiere-uxp/lib/session.js +85 -0
  122. package/dist/premiere-uxp/lib/sizing.js +325 -0
  123. package/dist/premiere-uxp/lib/time.js +88 -0
  124. package/dist/premiere-uxp/lib/timeline.js +336 -0
  125. package/dist/premiere-uxp/lib/verbs.js +21 -0
  126. package/dist/premiere-uxp/lib/write.js +97 -0
  127. package/dist/premiere-uxp/manifest.json +102 -0
  128. package/dist/probe-F7WQHMIA.js +3 -0
  129. package/dist/prores-RIG37OIH.js +526 -0
  130. package/dist/r3d-CXUNG6VS.js +1025 -0
  131. package/dist/r3d-T5O6IIZZ.js +3 -0
  132. package/dist/resolve-bridge.py +2286 -0
  133. package/dist/resolve-presets/conform.tools.xml +127 -0
  134. package/dist/source-QGWWLMME.js +3 -0
  135. package/dist/statusline-GMMCFMOA.js +4 -0
  136. package/dist/statusline.js +3 -0
  137. package/dist/still-P4JJNTEO.js +3 -0
  138. package/dist/still-wasm-DN5LPASS.js +3 -0
  139. package/dist/store-7IOEBOZY.js +3 -0
  140. package/dist/tiff-wasm-BPRDR6EB.js +3 -0
  141. package/dist/timeline-DQG6TVPF.js +3 -0
  142. package/dist/timeline_core-IOENXK4Z.js +3 -0
  143. package/dist/timeline_core_bg-JW42YM3G.js +3 -0
  144. package/dist/udf_bg-B37GKRIH.js +3 -0
  145. package/dist/wasm/media_core_bg.wasm +0 -0
  146. package/dist/wasm/udf_bg.wasm +0 -0
  147. package/dist/wasm-threads/media_core_bg.wasm +0 -0
  148. package/dist/wav-64SC6P7U.js +3 -0
  149. package/package.json +6 -4
@@ -0,0 +1,1037 @@
1
+ """The Flame verb table: the capability verbs of `hosts/base.py`, answered
2
+ from Flame's Python API.
3
+
4
+ Everything here runs on Flame's MAIN thread (the client marshals each call
5
+ through `flame.schedule_idle_event`); nothing here starts a thread or blocks.
6
+ The `flame` module is injected, so the tests drive this file with a fake.
7
+
8
+ Conventions (docs/INTERNAL_HOST_BRIDGE.md "Flame" has the evidence for each):
9
+
10
+ * **Timelines** are the PySequences on the desktop's reels, then those in the
11
+ workspace's OPEN libraries (folders and reels inside included). A closed
12
+ library cannot be read until it is opened, and the hook never opens one.
13
+ * **Frames** are ABSOLUTE timecode frames, read from `PyTime.frame` (with a
14
+ timecode-string fallback): `start_frame` is the sequence's start timecode,
15
+ `item_start`/`item_end` are record frames with an EXCLUSIVE end
16
+ (`record_in + record_duration`). Timeline markers are relative to the
17
+ sequence start (Resolve's convention); segment markers are in clip frames:
18
+ `left_offset + (record location - item_start)`.
19
+ * **Dynamic attributes** (`name`, `comment`, `colour`, `current_time`, every
20
+ marker field) come back as PyAttribute; `_v()` unwraps them.
21
+ * **Tracks**: video track N is the N-th track walking `versions[*].tracks[*]`;
22
+ audio track N is `audio_tracks[N-1]` (its first channel's segments).
23
+ * **Colours**: marker RGB <-> the neutral names by nearest match
24
+ (`ctpeer.neutral`). **Custom data** rides in the comment as `[ct:<custom>]`.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import os
30
+ import tempfile
31
+ import time
32
+ import xml.etree.ElementTree as ET
33
+ from typing import Any, Callable, Dict, List, Optional, Tuple
34
+
35
+ from ctpeer import Handles, PeerError
36
+ from ctpeer import neutral as N
37
+
38
+ from .building import BuildVerbs
39
+ from .render import FrameVerbs, RenderVerbs
40
+ from .util import _s, _v, parse_rate # noqa: F401 (parse_rate is part of this module's surface)
41
+
42
+ MODEL_SCHEMA = 1
43
+ CAPABILITIES = ["session", "timeline_read", "markers", "clip_meta", "item_meta", "timeline_write", "render", "frames"]
44
+ #: The optional verbs (`hosts/base.py` OPTIONAL) Flame really answers.
45
+ OPTIONAL_VERBS = [
46
+ "timeline_read.set_current_frame", "timeline_read.item_media", "timeline_read.end_frame",
47
+ "timeline_read.start_timecode", "timeline_read.item_enabled", "timeline_read.track_enabled",
48
+ "timeline_read.track_name", "timeline_read.item_source_end", "timeline_read.item_right_offset",
49
+ "timeline_read.item_track", "timeline_read.item_speed", "timeline_read.selected_items",
50
+ "timeline_read.item_clip",
51
+ "clip_meta.clip_info", "clip_meta.add_folder", "clip_meta.move_clips", "clip_meta.delete_clips",
52
+ "item_meta.set_enabled",
53
+ "timeline_write.import_file",
54
+ "render.jobs", "render.remove_all", "render.is_rendering", "render.presets", "render.preset_info",
55
+ "render.formats", "render.codecs", "render.current_output",
56
+ "frames.can_grab_track",
57
+ ]
58
+
59
+ #: How long the pool index behind `item_clip` may be reused (s). It is also
60
+ #: dropped on every write this hook makes.
61
+ POOL_INDEX_TTL = 3.0
62
+
63
+ #: Clip properties the renamer may write. Everything else is read-only.
64
+ WRITABLE_CLIP_PROPS = ("Clip Name", "Shot")
65
+
66
+
67
+ class FlamePeer(BuildVerbs, RenderVerbs, FrameVerbs):
68
+ """One peer per Flame session: the handle table plus the verbs
69
+ (`BuildVerbs`: timeline_write; `RenderVerbs`: the render queue)."""
70
+
71
+ def __init__(self, flame: Any):
72
+ self.flame = flame
73
+ self.handles = Handles()
74
+ #: item / source handle id -> (sequence, kind, track index): a segment
75
+ #: does not know which sequence's clock its PyTimes are on.
76
+ self._owner: Dict[str, Tuple[Any, str, int]] = {}
77
+ self._root_id = ""
78
+ self._pool_index: Optional[Tuple[float, Dict[Tuple[str, str], Any]]] = None
79
+ RenderVerbs.__init__(self)
80
+
81
+ # ── plumbing ────────────────────────────────────────────────────────
82
+ def _log_console(self, message: str) -> None:
83
+ """Flame's message bar. Called ON the main thread only (idle events)."""
84
+ try:
85
+ self.flame.messages.show_in_console(f"CONFORM.TOOLS: {message}", "info", 6)
86
+ except Exception:
87
+ pass
88
+
89
+ def verbs(self) -> Dict[str, Callable[..., Any]]:
90
+ table: Dict[str, Callable[..., Any]] = {}
91
+ for name in dir(self):
92
+ if name.startswith("v_"):
93
+ cap, _, verb = name[2:].partition("__")
94
+ table[f"{cap}.{verb}"] = getattr(self, name)
95
+ return table
96
+
97
+ def _project(self) -> Any:
98
+ try:
99
+ p = self.flame.projects.current_project
100
+ except Exception:
101
+ p = None
102
+ if p is None:
103
+ raise PeerError("no_project", "No project open")
104
+ return p
105
+
106
+ def _workspace(self) -> Any:
107
+ ws = getattr(self._project(), "current_workspace", None)
108
+ if ws is None:
109
+ raise PeerError("no_project", "No workspace open")
110
+ return ws
111
+
112
+ @staticmethod
113
+ def _key(obj: Any) -> Any:
114
+ try:
115
+ nid = obj.get_wiretap_node_id()
116
+ if nid:
117
+ return ("wt", str(nid))
118
+ except Exception:
119
+ pass
120
+ uid = _s(getattr(obj, "uid", "")) if hasattr(obj, "uid") else ""
121
+ return ("uid", uid) if uid else None
122
+
123
+ def _wrap(self, kind: str, obj: Any) -> Any:
124
+ return self.handles.wrap(kind, obj, self._key(obj))
125
+
126
+ @staticmethod
127
+ def _is_sequence(obj: Any) -> bool:
128
+ return type(obj).__name__ == "PySequence" or (hasattr(obj, "versions") and hasattr(obj, "open") and hasattr(obj, "create_marker") and not hasattr(obj, "clips"))
129
+
130
+ @staticmethod
131
+ def _is_gap(seg: Any) -> bool:
132
+ return "gap" in _s(getattr(seg, "type", "")).lower()
133
+
134
+ # ── time ────────────────────────────────────────────────────────────
135
+ def _rate(self, seq: Any) -> Tuple[float, bool]:
136
+ return parse_rate(getattr(seq, "frame_rate", ""))
137
+
138
+ def _abs(self, t: Any, fps: float, drop: bool = False) -> int:
139
+ """An absolute frame from a PyTime (`.frame`), else its timecode."""
140
+ t = _v(t)
141
+ if t is None:
142
+ return 0
143
+ if isinstance(t, (int, float)):
144
+ return int(t)
145
+ fr = getattr(t, "frame", None)
146
+ if isinstance(fr, (int, float)):
147
+ return int(fr)
148
+ tc = getattr(t, "timecode", None) or str(t)
149
+ try:
150
+ return N.tc_to_frames(str(tc).strip("'"), fps, drop if drop else None)
151
+ except ValueError:
152
+ return 0
153
+
154
+ def _count(self, t: Any, fps: float) -> int:
155
+ """A frame COUNT from a duration PyTime (`relative_frame`), an int, or
156
+ a timecode string."""
157
+ t = _v(t)
158
+ if t is None:
159
+ return 0
160
+ if isinstance(t, (int, float)):
161
+ return int(t)
162
+ rf = getattr(t, "relative_frame", None)
163
+ if isinstance(rf, (int, float)):
164
+ return int(rf)
165
+ try:
166
+ return N.tc_to_frames(str(getattr(t, "timecode", None) or t).strip("'"), fps)
167
+ except ValueError:
168
+ return 0
169
+
170
+ def _pytime(self, seq: Any, frame: int) -> Any:
171
+ return self.flame.PyTime(int(frame), _s(getattr(seq, "frame_rate", "")) or "24 fps")
172
+
173
+ def _start(self, seq: Any) -> int:
174
+ fps, drop = self._rate(seq)
175
+ st = getattr(seq, "start_time", None)
176
+ if st is not None and _v(st) is not None:
177
+ return self._abs(st, fps, drop)
178
+ return 0
179
+
180
+ # ── the project's sequences ─────────────────────────────────────────
181
+ def _reel_sequences(self, reel: Any) -> List[Any]:
182
+ return list(getattr(reel, "sequences", None) or [])
183
+
184
+ def _container_sequences(self, c: Any) -> List[Any]:
185
+ out = list(getattr(c, "sequences", None) or [])
186
+ for rg in getattr(c, "reel_groups", None) or []:
187
+ for reel in getattr(rg, "reels", None) or []:
188
+ out += self._reel_sequences(reel)
189
+ for reel in getattr(c, "reels", None) or []:
190
+ out += self._reel_sequences(reel)
191
+ for folder in getattr(c, "folders", None) or []:
192
+ out += self._container_sequences(folder)
193
+ return out
194
+
195
+ def _library_open(self, lib: Any) -> bool:
196
+ o = _v(getattr(lib, "opened", True))
197
+ return bool(True if o is None else o)
198
+
199
+ def _sequences(self) -> List[Any]:
200
+ ws = self._workspace()
201
+ out: List[Any] = []
202
+ desktop = getattr(ws, "desktop", None)
203
+ if desktop is not None:
204
+ for rg in getattr(desktop, "reel_groups", None) or []:
205
+ for reel in getattr(rg, "reels", None) or []:
206
+ out += self._reel_sequences(reel)
207
+ for lib in getattr(ws, "libraries", None) or []:
208
+ if self._library_open(lib):
209
+ out += self._container_sequences(lib)
210
+ return out
211
+
212
+ def _same(self, a: Any, b: Any) -> bool:
213
+ if a is b:
214
+ return True
215
+ ka, kb = self._key(a), self._key(b)
216
+ return ka is not None and ka == kb
217
+
218
+ def _current_seq(self) -> Optional[Any]:
219
+ tl = getattr(self.flame, "timeline", None)
220
+ clip = _v(getattr(tl, "clip", None)) if tl is not None else None
221
+ if clip is not None and self._is_sequence(clip):
222
+ return clip
223
+ seqs = self._sequences()
224
+ return seqs[0] if seqs else None
225
+
226
+ def _seq(self, handle: Any) -> Any:
227
+ return self.handles.get(handle, "seq")
228
+
229
+ # ── tracks and segments ─────────────────────────────────────────────
230
+ def _video_tracks(self, seq: Any) -> List[Any]:
231
+ out = []
232
+ for ver in getattr(seq, "versions", None) or []:
233
+ out += list(getattr(ver, "tracks", None) or [])
234
+ return out
235
+
236
+ def _audio_tracks(self, seq: Any) -> List[Any]:
237
+ return list(getattr(seq, "audio_tracks", None) or [])
238
+
239
+ def _track_segments(self, track: Any) -> List[Any]:
240
+ segs = getattr(track, "segments", None)
241
+ if segs is None: # an audio track: its first channel carries the edit
242
+ chans = list(getattr(track, "channels", None) or [])
243
+ segs = getattr(chans[0], "segments", None) if chans else None
244
+ return [s for s in (segs or []) if not self._is_gap(s)]
245
+
246
+ def _tracks(self, seq: Any, kind: str) -> List[Any]:
247
+ return self._audio_tracks(seq) if str(kind or "video").lower() == "audio" else self._video_tracks(seq)
248
+
249
+ def _item(self, seq: Any, kind: str, ti: int, seg: Any) -> Any:
250
+ fps, drop = self._rate(seq)
251
+ key = ("seg", self._key(seq) or id(seq), kind, ti, self._abs(getattr(seg, "record_in", None), fps, drop))
252
+ h = self.handles.wrap("item", seg, key)
253
+ self._owner[self.handles.id_of(h)] = (seq, kind, ti)
254
+ return h
255
+
256
+ def _seg(self, handle: Any) -> Tuple[Any, Any]:
257
+ seg = self.handles.get(handle, "item")
258
+ owner = self._owner.get(self.handles.id_of(handle))
259
+ seq = owner[0] if owner else self._current_seq()
260
+ return seg, seq
261
+
262
+ def _seg_times(self, seg: Any, seq: Any) -> Dict[str, Any]:
263
+ fps, drop = self._rate(seq)
264
+ rec_in = self._abs(getattr(seg, "record_in", None), fps, drop)
265
+ rec_dur = self._count(getattr(seg, "record_duration", None), fps)
266
+ if rec_dur <= 0:
267
+ rec_dur = max(0, self._abs(getattr(seg, "record_out", None), fps, drop) - rec_in)
268
+ src_fps = parse_rate(getattr(seg, "source_frame_rate", ""))[0] if _s(getattr(seg, "source_frame_rate", "")) else fps
269
+ src_in = self._abs(getattr(seg, "source_in", None), src_fps)
270
+ src_dur = self._count(getattr(seg, "source_duration", None), src_fps)
271
+ head = _v(getattr(seg, "head", None))
272
+ head = int(head) if isinstance(head, (int, float)) else None # "Infinite" on unlinked media
273
+ return {"rec_in": rec_in, "rec_out": rec_in + rec_dur, "src_in": src_in, "src_dur": src_dur,
274
+ "head": head, "src_fps": src_fps, "fps": fps}
275
+
276
+ def _left_offset(self, t: Dict[str, Any]) -> int:
277
+ return t["head"] if t["head"] is not None else 0
278
+
279
+ # ── speed ───────────────────────────────────────────────────────────
280
+ def _timewarp(self, seg: Any) -> Optional[Any]:
281
+ for fx in getattr(seg, "effects", None) or []:
282
+ if _s(getattr(fx, "type", "")) == "Timewarp":
283
+ return fx
284
+ return None
285
+
286
+ def speed_of(self, seg: Any, times: Dict[str, Any]) -> Dict[str, Any]:
287
+ """`{speed, variable, source}`: the Timewarp's own speed where the API
288
+ has it (`PyTimewarpTimelineFX.get_speed`, Flame 2026.1+), else its
289
+ saved setup (`TW_Speed`, percent), else source/record durations."""
290
+ rec = max(1, times["rec_out"] - times["rec_in"])
291
+ derived = times["src_dur"] / rec if times["src_dur"] else 1.0
292
+ fx = self._timewarp(seg)
293
+ if fx is None:
294
+ return {"speed": 1.0 if abs(derived - 1.0) < 1e-6 or not times["src_dur"] else derived, "variable": False, "source": "durations"}
295
+ get_speed = getattr(fx, "get_speed", None)
296
+ if callable(get_speed):
297
+ try:
298
+ mode = _s(getattr(fx, "mode", "Speed")) or "Speed"
299
+ first = float(get_speed(1.0))
300
+ last = float(get_speed(float(rec)))
301
+ return {"speed": first / 100.0 if abs(first) > 10 else first, "variable": mode != "Speed" or abs(first - last) > 1e-6,
302
+ "source": "timewarp_api"}
303
+ except Exception:
304
+ pass
305
+ setup = self._timewarp_setup(fx)
306
+ if setup:
307
+ return setup
308
+ return {"speed": derived, "variable": False, "source": "durations"}
309
+
310
+ def _timewarp_setup(self, fx: Any) -> Optional[Dict[str, Any]]:
311
+ save = getattr(fx, "save_setup", None)
312
+ if not callable(save):
313
+ return None
314
+ fd, path = tempfile.mkstemp(prefix="ct_tw_", suffix=".timewarp_node")
315
+ os.close(fd)
316
+ try:
317
+ if not save(path):
318
+ return None
319
+ root = ET.parse(path).getroot()
320
+ mode = root.findtext(".//State/TW_RetimerMode")
321
+ value = root.findtext(".//TW_Speed/Channel/Value")
322
+ keys = root.findtext(".//TW_SpeedTiming/Channel/Size") or root.findtext(".//TW_Speed/Channel/Size")
323
+ if value is None:
324
+ return None
325
+ variable = (mode not in (None, "", "0")) or (keys not in (None, "", "0", "1"))
326
+ return {"speed": float(value) / 100.0, "variable": variable, "source": "timewarp_setup"}
327
+ except Exception:
328
+ return None
329
+ finally:
330
+ try:
331
+ os.remove(path)
332
+ except OSError:
333
+ pass
334
+
335
+ # ── session ─────────────────────────────────────────────────────────
336
+ def v_session__current_project(self) -> Any:
337
+ try:
338
+ p = self.flame.projects.current_project
339
+ except Exception:
340
+ return None
341
+ return self.handles.wrap("project", p, ("project", _s(getattr(p, "name", "")))) if p is not None else None
342
+
343
+ def v_session__current_timeline(self, project: Any = None) -> Any:
344
+ seq = self._current_seq()
345
+ return self._wrap("seq", seq) if seq is not None else None
346
+
347
+ def v_session__timeline_count(self, project: Any = None) -> int:
348
+ return len(self._sequences())
349
+
350
+ def v_session__timeline_by_index(self, project: Any = None, index: int = 1) -> Any:
351
+ seqs = self._sequences()
352
+ i = int(index)
353
+ return self._wrap("seq", seqs[i - 1]) if 1 <= i <= len(seqs) else None
354
+
355
+ def v_session__set_current_timeline(self, project: Any = None, timeline: Any = None) -> bool:
356
+ seq = self._seq(timeline)
357
+ opener = getattr(seq, "open", None)
358
+ if not callable(opener):
359
+ return False
360
+ return bool(opener() is not False)
361
+
362
+ def v_session__name(self, handle: Any) -> str:
363
+ if self.handles.kind_of(handle) == "src":
364
+ return str(self._source_props(handle)["Clip Name"])
365
+ return _s(getattr(self.handles.get(handle), "name", ""))
366
+
367
+ def v_session__set_name(self, handle: Any, name: str) -> bool:
368
+ obj = self.handles.get(handle)
369
+ if self.handles.kind_of(handle) in ("project", "src"):
370
+ return False # a project is renamed in Project Management; a segment source has no name of its own
371
+ try:
372
+ obj.name = str(name)
373
+ except Exception as e:
374
+ raise PeerError("read_only", f"Flame refused the rename: {e}")
375
+ return _s(getattr(obj, "name", "")) == str(name)
376
+
377
+ def v_session__unique_id(self, handle: Any) -> str:
378
+ obj = self.handles.get(handle)
379
+ if self.handles.kind_of(handle) == "src":
380
+ kind, value = self._source_key(obj)
381
+ return f"src:{kind}:{value}"
382
+ key = self._key(obj)
383
+ return key[1] if key else self.handles.id_of(handle)
384
+
385
+ # ── timeline_read ───────────────────────────────────────────────────
386
+ def v_timeline_read__model(self, timeline: Any, project: Any = None) -> Dict[str, Any]:
387
+ seq = self._seq(timeline)
388
+ fps, drop = self._rate(seq)
389
+ start = self._start(seq)
390
+ raster = [int(_v(getattr(seq, "width", 0)) or 0), int(_v(getattr(seq, "height", 0)) or 0)]
391
+ items, tracks, states = [], [], {}
392
+ for ti, track in enumerate(self._video_tracks(seq), 1):
393
+ hidden = bool(_v(getattr(track, "hidden", False)) or False)
394
+ states[str(ti)] = not hidden
395
+ rows = []
396
+ for seg in self._track_segments(track):
397
+ row = self._row(seq, "video", ti, seg, not hidden)
398
+ if row["end"] > row["start"]:
399
+ rows.append(row)
400
+ items.append(row)
401
+ tracks.append({"index": ti, "enabled": not hidden, "items": rows, "name": _s(getattr(track, "name", ""))})
402
+ audio = []
403
+ for ai, track in enumerate(self._audio_tracks(seq), 1):
404
+ for seg in self._track_segments(track):
405
+ t = self._seg_times(seg, seq)
406
+ audio.append({"track": ai, "name": _s(getattr(seg, "name", "")), "start": t["rec_in"], "end": t["rec_out"],
407
+ "file_path": _s(getattr(seg, "file_path", ""))})
408
+ transitions = []
409
+ for ti, track in enumerate(self._video_tracks(seq), 1):
410
+ for tr in getattr(track, "transitions", None) or []:
411
+ kind = _s(getattr(tr, "type", "")).lower()
412
+ if not kind or kind == "cut":
413
+ continue
414
+ at = self._abs(getattr(tr, "record_time", None), fps, drop)
415
+ dur = self._count(getattr(tr, "duration", None), fps)
416
+ off = self._count(getattr(tr, "in_offset", None), fps)
417
+ transitions.append({"start": at - off, "end": at - off + dur, "track": ti, "kind": "dissolve" if "dissolve" in kind else kind})
418
+ items.sort(key=lambda r: (r["start"], r["track"]))
419
+ return {
420
+ "model_schema": MODEL_SCHEMA, "timeline": _s(getattr(seq, "name", "")), "start_frame": start, "fps": fps,
421
+ "drop_frame": drop, "items": items, "tracks": tracks, "track_states": states, "transitions": transitions,
422
+ "audio_items": audio, "audio_track_count": len(self._audio_tracks(seq)),
423
+ "playhead": self._playhead(seq), "source": "flame", "format": "flame", "raster": raster,
424
+ "sizing_basis": None, "markers": {}, "timelines": [], "timeline_index": None,
425
+ }
426
+
427
+ def _row(self, seq: Any, kind: str, ti: int, seg: Any, track_enabled: bool) -> Dict[str, Any]:
428
+ t = self._seg_times(seg, seq)
429
+ sp = self.speed_of(seg, t)
430
+ speed = float(sp["speed"] or 1.0)
431
+ reversed_ = speed < 0
432
+ dur = max(1, t["rec_out"] - t["rec_in"])
433
+ left = t["head"]
434
+ src_abs_in = t["src_in"]
435
+ src_len = t["src_dur"] or int(round(dur * abs(speed)))
436
+ path = _s(getattr(seg, "file_path", ""))
437
+ handle = self._item(seq, kind, ti, seg)
438
+ rel_in = left if left is not None else src_abs_in
439
+ return {
440
+ "clip_id": handle["$h"], "name": _s(getattr(seg, "name", "")) or _s(getattr(seg, "source_name", "")),
441
+ "mpi_id": _s(getattr(seg, "source_uid", "")), "track": ti, "start": t["rec_in"], "end": t["rec_out"],
442
+ "enabled": not bool(_v(getattr(seg, "hidden", False)) or False), "track_enabled": track_enabled,
443
+ "src_in": rel_in, "src_out": rel_in + src_len, "src_relative": left is not None,
444
+ "src_abs_in": src_abs_in, "src_abs_out": src_abs_in + src_len,
445
+ "speed": round(abs(speed), 4), "speed_derived": round((t["src_dur"] or dur) / dur, 4), "fps_factor": round(t["src_fps"] / t["fps"], 6) if t["fps"] else 1.0,
446
+ "speed_reported": round(abs(speed), 4), "speed_is_variable": bool(sp["variable"]), "speed_listed": sp["source"] != "durations",
447
+ "speed_source": sp["source"], "reversed": reversed_,
448
+ "sizing": None, "nodes": None, "markers": {}, "flags": [], "color": "",
449
+ "reel": _s(getattr(seg, "tape_name", "")), "tape_name": _s(getattr(seg, "tape_name", "")),
450
+ "shot_name": _s(getattr(seg, "shot_name", "")), "source_name": _s(getattr(seg, "source_name", "")),
451
+ "file_name": os.path.basename(path) if path else "", "file_path": path,
452
+ "start_tc": (src_abs_in - left) if left is not None else None,
453
+ "source_id": _s(getattr(seg, "source_uid", "")), "nested": False, "item": None, "src_fps": t["src_fps"],
454
+ "handle": handle,
455
+ }
456
+
457
+ def _playhead(self, seq: Any) -> Optional[int]:
458
+ ct = getattr(seq, "current_time", None)
459
+ if ct is None or _v(ct) is None:
460
+ return None
461
+ fps, drop = self._rate(seq)
462
+ return self._abs(ct, fps, drop)
463
+
464
+ def v_timeline_read__start_frame(self, timeline: Any) -> int:
465
+ return self._start(self._seq(timeline))
466
+
467
+ def v_timeline_read__setting(self, handle: Any, key: str) -> Any:
468
+ if self.handles.kind_of(handle) != "seq":
469
+ return None # a PROJECT setting (Resolve's colorSpaceOutput ...): Flame keeps none we can read
470
+ seq = self._seq(handle)
471
+ fps, drop = self._rate(seq)
472
+ w, h = int(_v(getattr(seq, "width", 0)) or 0), int(_v(getattr(seq, "height", 0)) or 0)
473
+ table = {"timelineFrameRate": fps, "timelineResolutionWidth": w, "timelineResolutionHeight": h,
474
+ "timelineOutputResolutionWidth": w, "timelineOutputResolutionHeight": h,
475
+ "timelineDropFrameTimecode": "1" if drop else "0", "timelinePlaybackFrameRate": fps}
476
+ return table.get(str(key))
477
+
478
+ def v_timeline_read__track_count(self, timeline: Any, kind: str = "video") -> int:
479
+ return len(self._tracks(self._seq(timeline), kind))
480
+
481
+ def v_timeline_read__items_in_track(self, timeline: Any, kind: str = "video", index: int = 1) -> List[Any]:
482
+ seq = self._seq(timeline)
483
+ tracks = self._tracks(seq, kind)
484
+ i = int(index)
485
+ if not 1 <= i <= len(tracks):
486
+ return []
487
+ k = "audio" if str(kind).lower() == "audio" else "video"
488
+ return [self._item(seq, k, i, s) for s in self._track_segments(tracks[i - 1])]
489
+
490
+ def v_timeline_read__item_start(self, item: Any) -> int:
491
+ seg, seq = self._seg(item)
492
+ return self._seg_times(seg, seq)["rec_in"]
493
+
494
+ def v_timeline_read__item_end(self, item: Any) -> int:
495
+ seg, seq = self._seg(item)
496
+ return self._seg_times(seg, seq)["rec_out"]
497
+
498
+ def v_timeline_read__item_left_offset(self, item: Any) -> int:
499
+ seg, seq = self._seg(item)
500
+ return self._left_offset(self._seg_times(seg, seq))
501
+
502
+ def v_timeline_read__item_source_start(self, item: Any) -> int:
503
+ """Frames into the MEDIA (the segment's head), like Resolve's
504
+ GetSourceStartFrame on a movie - what a placement's `source_in` and
505
+ the media's frame count are measured in. Unlinked media ("Infinite"
506
+ head) has no start: the source timecode frame stands in."""
507
+ seg, seq = self._seg(item)
508
+ t = self._seg_times(seg, seq)
509
+ return t["head"] if t["head"] is not None else t["src_in"]
510
+
511
+ def _segment_media(self, seg: Any, t: Dict[str, Any]) -> Dict[str, Any]:
512
+ """`base.MEDIA_KEYS` for a segment. `offline`: the FILE decides - a
513
+ path that is not on disk; a segment with no path is never offline."""
514
+ path = _s(getattr(seg, "file_path", ""))
515
+ out: Dict[str, Any] = {"id": _s(getattr(seg, "source_uid", "")) or path or _s(getattr(seg, "source_name", "")),
516
+ "name": _s(getattr(seg, "source_name", "")) or _s(getattr(seg, "name", "")),
517
+ "file_path": path, "fps": t["src_fps"], "reel": _s(getattr(seg, "tape_name", "")),
518
+ "type": "video", "offline": bool(path) and not os.path.exists(path)}
519
+ w, h = _v(getattr(seg, "source_width", None)), _v(getattr(seg, "source_height", None))
520
+ if isinstance(w, (int, float)) and isinstance(h, (int, float)) and w and h:
521
+ out["resolution"] = f"{int(w)}x{int(h)}"
522
+ if t["head"] is not None:
523
+ out["start_tc"] = t["src_in"] - t["head"]
524
+ tail = _v(getattr(seg, "tail", None))
525
+ if t["head"] is not None and isinstance(tail, (int, float)):
526
+ out["frames"] = int(t["head"]) + int(t["src_dur"]) + int(tail)
527
+ return {k: v for k, v in out.items() if v not in (None, "")}
528
+
529
+ def v_timeline_read__item_media(self, item: Any) -> Dict[str, Any]:
530
+ seg, seq = self._seg(item)
531
+ return self._segment_media(seg, self._seg_times(seg, seq))
532
+
533
+ def v_timeline_read__end_frame(self, timeline: Any) -> Optional[int]:
534
+ seq = self._seq(timeline)
535
+ fps, _ = self._rate(seq)
536
+ dur = self._count(getattr(seq, "duration", None), fps)
537
+ return self._start(seq) + dur if dur else None
538
+
539
+ def v_timeline_read__start_timecode(self, timeline: Any) -> str:
540
+ seq = self._seq(timeline)
541
+ fps, drop = self._rate(seq)
542
+ return N.frames_to_tc(self._start(seq), fps, drop)
543
+
544
+ def v_timeline_read__item_enabled(self, item: Any) -> bool:
545
+ seg, _ = self._seg(item)
546
+ return not bool(_v(getattr(seg, "hidden", False)) or False)
547
+
548
+ def _track_at(self, timeline: Any, kind: str, index: int) -> Optional[Any]:
549
+ tracks = self._tracks(self._seq(timeline), kind)
550
+ i = int(index)
551
+ return tracks[i - 1] if 1 <= i <= len(tracks) else None
552
+
553
+ def v_timeline_read__track_enabled(self, timeline: Any, kind: str = "video", index: int = 1) -> Optional[bool]:
554
+ track = self._track_at(timeline, kind, index)
555
+ if track is None:
556
+ return None
557
+ hidden = _v(getattr(track, "hidden", None))
558
+ return None if hidden is None else not bool(hidden)
559
+
560
+ def v_timeline_read__track_name(self, timeline: Any, kind: str = "video", index: int = 1) -> str:
561
+ track = self._track_at(timeline, kind, index)
562
+ return _s(getattr(track, "name", "")) if track is not None else ""
563
+
564
+ def v_timeline_read__item_source_end(self, item: Any) -> Optional[int]:
565
+ """`item_source_start` + the source frames shown (exclusive)."""
566
+ seg, seq = self._seg(item)
567
+ t = self._seg_times(seg, seq)
568
+ if not t["src_dur"]:
569
+ return None
570
+ return (t["head"] if t["head"] is not None else t["src_in"]) + t["src_dur"]
571
+
572
+ def v_timeline_read__item_right_offset(self, item: Any) -> Optional[int]:
573
+ seg, _ = self._seg(item)
574
+ tail = _v(getattr(seg, "tail", None))
575
+ return int(tail) if isinstance(tail, (int, float)) else None # "Infinite" on unlinked media
576
+
577
+ def v_timeline_read__item_track(self, item: Any) -> Optional[List[Any]]:
578
+ self.handles.get(item, "item")
579
+ owner = self._owner.get(self.handles.id_of(item))
580
+ return [owner[1], owner[2]] if owner else None
581
+
582
+ # ── the source behind a segment (item_clip) ─────────────────────────
583
+ def _source_key(self, seg: Any) -> Tuple[str, str]:
584
+ uid = _s(getattr(seg, "source_uid", ""))
585
+ if uid:
586
+ return ("uid", uid)
587
+ path = _s(getattr(seg, "file_path", ""))
588
+ if path:
589
+ return ("path", path)
590
+ return ("name", f"{_s(getattr(seg, 'source_name', ''))}|{_s(getattr(seg, 'tape_name', ''))}")
591
+
592
+ def _invalidate_pool(self) -> None:
593
+ self._pool_index = None
594
+
595
+ def _pool_clips(self) -> List[Any]:
596
+ """Every Media Panel CLIP (not sequence) in the desktop reels and the
597
+ open libraries."""
598
+ out: List[Any] = []
599
+
600
+ def walk(c: Any) -> None:
601
+ out.extend(getattr(c, "clips", None) or [])
602
+ for attr in ("reel_groups", "reels", "folders"):
603
+ for child in getattr(c, attr, None) or []:
604
+ walk(child)
605
+
606
+ ws = self._workspace()
607
+ desktop = getattr(ws, "desktop", None)
608
+ if desktop is not None:
609
+ walk(desktop)
610
+ for lib in getattr(ws, "libraries", None) or []:
611
+ if self._library_open(lib):
612
+ walk(lib)
613
+ return [c for c in out if not self._is_sequence(c)]
614
+
615
+ def _pool_lookup(self) -> Dict[Tuple[str, str], Any]:
616
+ now = time.monotonic()
617
+ if self._pool_index is not None and now - self._pool_index[0] < POOL_INDEX_TTL:
618
+ return self._pool_index[1]
619
+ index: Dict[Tuple[str, str], Any] = {}
620
+ for clip in self._pool_clips():
621
+ seg = self._first_segment(clip)
622
+ if seg is None:
623
+ continue
624
+ for key in (("uid", _s(getattr(seg, "source_uid", ""))), ("path", _s(getattr(seg, "file_path", "")))):
625
+ if key[1] and key not in index:
626
+ index[key] = clip
627
+ self._pool_index = (now, index)
628
+ return index
629
+
630
+ def v_timeline_read__item_clip(self, item: Any) -> Any:
631
+ """The Media Panel clip on the SAME source (source uid, else file
632
+ path) when there is one; else a SOURCE handle - Flame's segment
633
+ source, which has no Media Panel entry: readable through
634
+ `session.name`, `clip_meta.clip_property` / `clip_info`, never listed
635
+ in a bin and never written. Nothing is created (`PySegment.match`
636
+ would make a clip; this never calls it). None for a segment with no
637
+ media at all (a colour source, a gap filler)."""
638
+ seg, seq = self._seg(item)
639
+ if not (_s(getattr(seg, "file_path", "")) or _s(getattr(seg, "source_name", "")) or _s(getattr(seg, "tape_name", ""))):
640
+ return None
641
+ index = self._pool_lookup()
642
+ for key in (("uid", _s(getattr(seg, "source_uid", ""))), ("path", _s(getattr(seg, "file_path", "")))):
643
+ if key[1] and key in index:
644
+ return self._wrap("clip", index[key])
645
+ h = self.handles.wrap("src", seg, ("src",) + self._source_key(seg))
646
+ self._owner[self.handles.id_of(h)] = (seq, "video", 0)
647
+ return h
648
+
649
+ def _source_props(self, handle: Any) -> Dict[str, Any]:
650
+ seg = self.handles.get(handle, "src")
651
+ owner = self._owner.get(self.handles.id_of(handle))
652
+ seq = owner[0] if owner else self._current_seq()
653
+ t = self._seg_times(seg, seq)
654
+ media = self._segment_media(seg, t)
655
+ name = media.get("name") or _s(getattr(seg, "name", ""))
656
+ fps = t["src_fps"]
657
+ start = media.get("start_tc")
658
+ return {
659
+ "Clip Name": name, "Type": "Video", "File Path": media.get("file_path", ""),
660
+ "Reel Name": media.get("reel", ""), "Tape Name": media.get("reel", ""),
661
+ "Shot": _s(getattr(seg, "shot_name", "")), "FPS": fps, "Frame Rate": _s(getattr(seg, "source_frame_rate", "")),
662
+ "Start TC": N.frames_to_tc(start, fps) if start is not None else "",
663
+ "Frames": media.get("frames", ""), "Resolution": media.get("resolution", ""),
664
+ }
665
+
666
+ def v_timeline_read__item_speed(self, item: Any, timeline_fps: Optional[float] = None) -> Dict[str, Any]:
667
+ seg, seq = self._seg(item)
668
+ t = self._seg_times(seg, seq)
669
+ sp = self.speed_of(seg, t)
670
+ factor = float(sp["speed"]) if sp["speed"] is not None else None
671
+ if factor is not None and sp["source"] == "durations" and timeline_fps and t["src_fps"]:
672
+ factor = factor * float(timeline_fps) / float(t["src_fps"]) # a frame-rate conversion is not a retime
673
+ if factor is not None and sp["source"] == "durations" and abs(factor - 1.0) < 1e-6:
674
+ factor = 1.0
675
+ return {"factor": factor, "reversed": bool(factor is not None and factor < 0), "variable": bool(sp["variable"])}
676
+
677
+ def v_timeline_read__selected_items(self, timeline: Any) -> List[Any]:
678
+ """Segments the user selected (`segment.selected`, a dynamic attribute)."""
679
+ seq = self._seq(timeline)
680
+ out = []
681
+ for ti, track in enumerate(self._video_tracks(seq), 1):
682
+ for seg in self._track_segments(track):
683
+ if bool(_v(getattr(seg, "selected", False)) or False):
684
+ out.append(self._item(seq, "video", ti, seg))
685
+ return out
686
+
687
+ def v_timeline_read__current_timecode(self, timeline: Any) -> str:
688
+ seq = self._seq(timeline)
689
+ fps, drop = self._rate(seq)
690
+ ph = self._playhead(seq)
691
+ return N.frames_to_tc(ph if ph is not None else self._start(seq), fps, drop)
692
+
693
+ def _set_playhead(self, seq: Any, frame: int) -> bool:
694
+ try:
695
+ seq.current_time = self._pytime(seq, frame)
696
+ except Exception:
697
+ return False
698
+ return self._playhead(seq) == int(frame)
699
+
700
+ def v_timeline_read__set_current_timecode(self, timeline: Any, timecode: str) -> bool:
701
+ seq = self._seq(timeline)
702
+ fps, drop = self._rate(seq)
703
+ try:
704
+ frame = N.tc_to_frames(timecode, fps, drop)
705
+ except ValueError as e:
706
+ raise PeerError("bad_params", str(e))
707
+ return self._set_playhead(seq, frame)
708
+
709
+ def v_timeline_read__set_current_frame(self, timeline: Any, frame: int) -> bool:
710
+ return self._set_playhead(self._seq(timeline), int(frame))
711
+
712
+ def v_timeline_read__current_video_item(self, timeline: Any) -> Any:
713
+ seq = self._seq(timeline)
714
+ ph = self._playhead(seq)
715
+ if ph is None:
716
+ return None
717
+ tracks = self._video_tracks(seq)
718
+ for ti in range(len(tracks), 0, -1): # top-most track first
719
+ for seg in self._track_segments(tracks[ti - 1]):
720
+ t = self._seg_times(seg, seq)
721
+ if t["rec_in"] <= ph < t["rec_out"]:
722
+ return self._item(seq, "video", ti, seg)
723
+ return None
724
+
725
+ # ── markers ─────────────────────────────────────────────────────────
726
+ def _marker_target(self, target: Any) -> Tuple[Any, Any, str]:
727
+ kind = self.handles.kind_of(target)
728
+ if kind == "seq":
729
+ seq = self._seq(target)
730
+ return seq, seq, "timeline"
731
+ if kind == "item":
732
+ seg, seq = self._seg(target)
733
+ return seg, seq, "clip"
734
+ raise PeerError("bad_handle", f"markers live on a sequence or a segment, not a {kind or 'non-handle'}")
735
+
736
+ def _marker_frame(self, m: Any, holder: Any, seq: Any, scope: str) -> int:
737
+ fps, drop = self._rate(seq)
738
+ loc = self._abs(getattr(m, "location", None), fps, drop)
739
+ if scope == "timeline":
740
+ return loc - self._start(seq)
741
+ t = self._seg_times(holder, seq)
742
+ return self._left_offset(t) + (loc - t["rec_in"])
743
+
744
+ def _marker_record(self, m: Any, holder: Any, seq: Any, scope: str) -> Dict[str, Any]:
745
+ fps, _ = self._rate(seq)
746
+ note, custom = N.decode_note(_s(getattr(m, "comment", "")))
747
+ colour = _v(getattr(m, "colour", None))
748
+ return {"frame": self._marker_frame(m, holder, seq, scope), "color": N.nearest_color(colour) if colour is not None else "",
749
+ "name": _s(getattr(m, "name", "")), "note": note, "duration": max(1, self._count(getattr(m, "duration", None), fps) or 1),
750
+ "custom_data": custom, "scope": scope, "keywords": _s(getattr(m, "colour_label", ""))}
751
+
752
+ def v_markers__list(self, target: Any) -> List[Dict[str, Any]]:
753
+ holder, seq, scope = self._marker_target(target)
754
+ out = [self._marker_record(m, holder, seq, scope) for m in (getattr(holder, "markers", None) or [])]
755
+ out.sort(key=lambda r: r["frame"])
756
+ return out
757
+
758
+ def _find_marker(self, holder: Any, seq: Any, scope: str, frame: int) -> Optional[Any]:
759
+ for m in getattr(holder, "markers", None) or []:
760
+ if self._marker_frame(m, holder, seq, scope) == int(frame):
761
+ return m
762
+ return None
763
+
764
+ def v_markers__add(self, target: Any, frame: int, color: str = "", name: str = "", note: str = "", duration: int = 1, custom_data: str = "") -> bool:
765
+ holder, seq, scope = self._marker_target(target)
766
+ if self._find_marker(holder, seq, scope, frame) is not None:
767
+ return False # one marker per frame, like every NLE
768
+ if scope == "timeline":
769
+ loc = self._start(seq) + int(frame)
770
+ else:
771
+ t = self._seg_times(holder, seq)
772
+ loc = t["rec_in"] + int(frame) - self._left_offset(t)
773
+ if not t["rec_in"] <= loc < t["rec_out"]:
774
+ return False # Flame keeps segment markers inside the segment
775
+ m = holder.create_marker(self._pytime(seq, loc))
776
+ if m is None:
777
+ return False
778
+ m.name = str(name or "")
779
+ m.comment = N.encode_note(note, custom_data)
780
+ rgb = N.color_rgb(color)
781
+ if rgb is not None:
782
+ m.colour = rgb
783
+ dur = max(1, int(duration or 1))
784
+ if dur > 1:
785
+ try:
786
+ m.duration = dur
787
+ except Exception:
788
+ pass
789
+ return True
790
+
791
+ def v_markers__delete_at(self, target: Any, frame: int) -> bool:
792
+ holder, seq, scope = self._marker_target(target)
793
+ m = self._find_marker(holder, seq, scope, frame)
794
+ if m is None:
795
+ return False
796
+ return bool(self.flame.delete(m, confirm=False))
797
+
798
+ # ── clip_meta ───────────────────────────────────────────────────────
799
+ def v_clip_meta__media_pool(self, project: Any = None) -> Any:
800
+ ws = self._workspace()
801
+ return self.handles.wrap("pool", ws, ("pool", "workspace"))
802
+
803
+ def v_clip_meta__root_folder(self, media_pool: Any) -> Any:
804
+ ws = self.handles.get(media_pool, "pool")
805
+ root = self.handles.wrap("bin", ws, ("bin", "root"))
806
+ self._root_id = self.handles.id_of(root)
807
+ return root
808
+
809
+ def v_clip_meta__current_folder(self, media_pool: Any) -> Any:
810
+ return self.v_clip_meta__root_folder(media_pool) # Flame has no "current bin"; the workspace stands in
811
+
812
+ def _children_bins(self, obj: Any, is_root: bool) -> List[Any]:
813
+ if is_root:
814
+ out = []
815
+ desktop = getattr(obj, "desktop", None)
816
+ if desktop is not None:
817
+ out.append(desktop)
818
+ out += [lib for lib in (getattr(obj, "libraries", None) or []) if self._library_open(lib)]
819
+ return out
820
+ out = []
821
+ for attr in ("folders", "reel_groups", "reels"):
822
+ out += list(getattr(obj, attr, None) or [])
823
+ return out
824
+
825
+ def v_clip_meta__subfolders(self, folder: Any) -> List[Any]:
826
+ obj = self.handles.get(folder, "bin")
827
+ is_root = self.handles.id_of(folder) == self._root_id
828
+ return [self.handles.wrap("bin", b, self._key(b)) for b in self._children_bins(obj, is_root)]
829
+
830
+ def v_clip_meta__clips(self, folder: Any) -> List[Any]:
831
+ obj = self.handles.get(folder, "bin")
832
+ out = []
833
+ for attr in ("clips", "sequences"):
834
+ for c in getattr(obj, attr, None) or []:
835
+ out.append(self._wrap("clip", c))
836
+ return out
837
+
838
+ def _first_segment(self, clip: Any) -> Optional[Any]:
839
+ for track in self._video_tracks(clip):
840
+ for seg in self._track_segments(track):
841
+ return seg
842
+ return None
843
+
844
+ def _clip_props(self, clip: Any) -> Dict[str, Any]:
845
+ fps, drop = self._rate(clip)
846
+ seg = self._first_segment(clip)
847
+ start = self._start(clip)
848
+ dur = self._count(getattr(clip, "duration", None), fps)
849
+ return {
850
+ "Clip Name": _s(getattr(clip, "name", "")),
851
+ "Type": "Timeline" if self._is_sequence(clip) else "Video",
852
+ "File Path": _s(getattr(seg, "file_path", "")) if seg is not None else "",
853
+ "Reel Name": _s(getattr(seg, "tape_name", "")) if seg is not None else "",
854
+ "Tape Name": _s(getattr(seg, "tape_name", "")) if seg is not None else "",
855
+ "Shot": _s(getattr(clip, "shot_name", "")) if hasattr(clip, "shot_name") else "",
856
+ "FPS": fps, "Frame Rate": _s(getattr(clip, "frame_rate", "")),
857
+ "Start TC": N.frames_to_tc(start, fps, drop), "Duration": N.frames_to_tc(dur, fps, drop) if dur else "",
858
+ "Resolution": f"{int(_v(getattr(clip, 'width', 0)) or 0)}x{int(_v(getattr(clip, 'height', 0)) or 0)}",
859
+ "Frames": dur if dur else "",
860
+ }
861
+
862
+ def v_clip_meta__clip_info(self, clip: Any) -> Dict[str, Any]:
863
+ """`base.MEDIA_KEYS` + `used` for a Media Panel clip. `used`: some
864
+ sequence of this workspace has a segment on the same file (or source).
865
+ A SOURCE handle (`item_clip`) is used by definition."""
866
+ if self.handles.kind_of(clip) == "src":
867
+ seg = self.handles.get(clip, "src")
868
+ owner = self._owner.get(self.handles.id_of(clip))
869
+ seq = owner[0] if owner else self._current_seq()
870
+ return {**self._segment_media(seg, self._seg_times(seg, seq)), "used": True}
871
+ obj = self.handles.get(clip, "clip", "seq")
872
+ fps, _ = self._rate(obj)
873
+ is_seq = self._is_sequence(obj)
874
+ seg = self._first_segment(obj)
875
+ out: Dict[str, Any] = {"id": self.v_session__unique_id(clip), "name": _s(getattr(obj, "name", "")), "fps": fps,
876
+ "type": "compound" if is_seq else "video"}
877
+ w, h = int(_v(getattr(obj, "width", 0)) or 0), int(_v(getattr(obj, "height", 0)) or 0)
878
+ if w and h:
879
+ out["resolution"] = f"{w}x{h}"
880
+ out["start_tc"] = self._start(obj)
881
+ dur = self._count(getattr(obj, "duration", None), fps)
882
+ if dur:
883
+ out["frames"] = dur
884
+ if seg is not None and not is_seq:
885
+ path = _s(getattr(seg, "file_path", ""))
886
+ out.update({"file_path": path, "reel": _s(getattr(seg, "tape_name", "")),
887
+ "offline": bool(path) and not os.path.exists(path)})
888
+ out["used"] = self._used(path, _s(getattr(seg, "source_uid", "")))
889
+ else:
890
+ out["used"] = False
891
+ return {k: v for k, v in out.items() if v not in (None, "")}
892
+
893
+ def _used(self, path: str, uid: str) -> bool:
894
+ if not path and not uid:
895
+ return False
896
+ for seq in self._sequences():
897
+ for track in self._video_tracks(seq) + self._audio_tracks(seq):
898
+ for seg in self._track_segments(track):
899
+ if (path and _s(getattr(seg, "file_path", "")) == path) or (uid and _s(getattr(seg, "source_uid", "")) == uid):
900
+ return True
901
+ return False
902
+
903
+ def v_clip_meta__clip_property(self, clip: Any, key: Optional[str] = None) -> Any:
904
+ if self.handles.kind_of(clip) == "src":
905
+ props = self._source_props(clip)
906
+ return props if key is None else props.get(str(key))
907
+ props = self._clip_props(self.handles.get(clip, "clip", "seq"))
908
+ return props if key is None else props.get(str(key))
909
+
910
+ def v_clip_meta__set_clip_property(self, clip: Any, key: str, value: Any) -> bool:
911
+ if self.handles.kind_of(clip) == "src":
912
+ return False # a segment source is read-only
913
+ obj = self.handles.get(clip, "clip", "seq")
914
+ if key not in WRITABLE_CLIP_PROPS:
915
+ return False # read-only in Flame (path, reel, TC...)
916
+ attr = "name" if key == "Clip Name" else "shot_name"
917
+ if attr == "shot_name" and not hasattr(obj, "shot_name"):
918
+ return False # PyClip.shot_name is 2026+
919
+ try:
920
+ setattr(obj, attr, str(value))
921
+ except Exception:
922
+ return False
923
+ return _s(getattr(obj, attr, "")) == str(value)
924
+
925
+ def v_clip_meta__add_folder(self, media_pool: Any = None, parent: Any = None, name: str = "") -> Any:
926
+ """A new bin under `parent`: under the root a LIBRARY (the workspace's
927
+ own `create_library`), under a library or folder a folder, under a
928
+ reel group a reel, under the desktop a reel group."""
929
+ obj = self.handles.get(parent, "bin")
930
+ name = str(name or "").strip()
931
+ if not name:
932
+ return None
933
+ kind = type(obj).__name__
934
+ if self.handles.id_of(parent) == self._root_id:
935
+ method = "create_library"
936
+ elif kind == "PyDesktop":
937
+ method = "create_reel_group"
938
+ elif kind == "PyReelGroup":
939
+ method = "create_reel"
940
+ elif kind in ("PyLibrary", "PyFolder"):
941
+ method = "create_folder"
942
+ else:
943
+ return None # a reel holds clips, not bins
944
+ make = getattr(obj, method, None)
945
+ if not callable(make):
946
+ return None
947
+ made = make(name)
948
+ self._invalidate_pool()
949
+ return self.handles.wrap("bin", made, self._key(made)) if made is not None else None
950
+
951
+ def v_clip_meta__move_clips(self, media_pool: Any = None, clips: Any = None, folder: Any = None) -> bool:
952
+ """`flame.media_panel.move` into a bin that holds clips (a reel, a
953
+ folder, a library). Source handles are not Media Panel entries."""
954
+ dest = self.handles.get(folder, "bin")
955
+ if self.handles.id_of(folder) == self._root_id or not hasattr(dest, "clips"):
956
+ return False
957
+ objs = [self.handles.get(c, "clip", "seq") for c in (clips or [])]
958
+ if not objs:
959
+ return False
960
+ moved = self.flame.media_panel.move(objs, dest)
961
+ self._invalidate_pool()
962
+ return moved is not None and (not isinstance(moved, list) or len(moved) == len(objs))
963
+
964
+ def v_clip_meta__delete_clips(self, media_pool: Any = None, clips: Any = None) -> bool:
965
+ """`flame.delete(clip, confirm=False)` per Media Panel clip (safe on a
966
+ clip or sequence; never on a reel or folder from here). The media
967
+ files are untouched; a segment that used the clip keeps its source."""
968
+ objs = [self.handles.get(c, "clip", "seq") for c in (clips or [])]
969
+ ok = bool(objs)
970
+ for obj in objs:
971
+ try:
972
+ ok = bool(self.flame.delete(obj, confirm=False)) and ok
973
+ except Exception:
974
+ ok = False
975
+ self._invalidate_pool()
976
+ return ok
977
+
978
+ # ── item_meta ───────────────────────────────────────────────────────
979
+ # A SEGMENT's colour (or a Media Panel clip's): RGB in Flame, Resolve's
980
+ # clip-colour names on the wire (nearest match, so a name written reads
981
+ # back as itself). Flame has no clip flags: the flag verbs say so with
982
+ # the `unsupported` code, which tools read as "this host has none".
983
+ def _colour_target(self, handle: Any) -> Any:
984
+ kind = self.handles.kind_of(handle)
985
+ if kind == "item":
986
+ return self._seg(handle)[0]
987
+ if kind in ("clip", "seq"):
988
+ return self.handles.get(handle, "clip", "seq")
989
+ raise PeerError("bad_handle", f"a colour lives on a segment or a Media Panel clip, not a {kind or 'non-handle'}")
990
+
991
+ def v_item_meta__color(self, handle: Any) -> str:
992
+ if self.handles.kind_of(handle) == "src":
993
+ return ""
994
+ rgb = _v(getattr(self._colour_target(handle), "colour", None))
995
+ return N.nearest_clip_color(rgb) if rgb not in (None, "") else ""
996
+
997
+ def v_item_meta__set_color(self, handle: Any, color: str) -> bool:
998
+ if self.handles.kind_of(handle) == "src":
999
+ return False
1000
+ rgb = N.clip_color_rgb(color)
1001
+ if rgb is None:
1002
+ return False
1003
+ obj = self._colour_target(handle)
1004
+ try:
1005
+ obj.colour = tuple(rgb)
1006
+ except Exception as e:
1007
+ raise PeerError("read_only", f"Flame refused the colour: {e}")
1008
+ got = _v(getattr(obj, "colour", None))
1009
+ return got not in (None, "") and N.nearest_clip_color(got) == N.nearest_clip_color(rgb)
1010
+
1011
+ def v_item_meta__clear_color(self, handle: Any) -> bool:
1012
+ if self.handles.kind_of(handle) == "src":
1013
+ return False
1014
+ obj = self._colour_target(handle)
1015
+ clear = getattr(obj, "clear_colour", None)
1016
+ if not callable(clear):
1017
+ return False
1018
+ clear()
1019
+ return True
1020
+
1021
+ def v_item_meta__flags(self, handle: Any) -> List[str]:
1022
+ return [] # Flame keeps no clip flags
1023
+
1024
+ def v_item_meta__add_flag(self, handle: Any, color: str) -> bool:
1025
+ raise PeerError("unsupported", "Flame has no clip flags (a segment carries a colour instead)")
1026
+
1027
+ def v_item_meta__clear_flags(self, handle: Any, color: Optional[str] = None) -> bool:
1028
+ raise PeerError("unsupported", "Flame has no clip flags (a segment carries a colour instead)")
1029
+
1030
+ def v_item_meta__set_enabled(self, item: Any, enabled: bool) -> bool:
1031
+ """Show / hide a segment (`hidden`, a dynamic attribute)."""
1032
+ seg, _ = self._seg(item)
1033
+ try:
1034
+ seg.hidden = not bool(enabled)
1035
+ except Exception:
1036
+ return False
1037
+ return (not bool(_v(getattr(seg, "hidden", False)) or False)) == bool(enabled)