pulse_pixelstream_types/
lib.rs

1//! Shared myko entity/command/report types for the pixelstreaming app. WASM-safe:
2//! the Leptos frontend and the native server both build against this crate, and
3//! the TS bindings are generated from it.
4//!
5//! One `#[myko_item]` per module (the macro emits per-module helpers that would
6//! otherwise collide).
7
8pub mod cam_pref;
9pub mod camera_home;
10pub mod collection;
11pub mod collection_membership;
12pub mod commands;
13pub mod control_lock;
14pub mod frame_capture;
15pub mod frame_capture_status;
16pub mod frame_capture_target;
17pub(crate) mod legacy_capture_run;
18pub(crate) mod legacy_shot_list;
19pub mod otio;
20pub mod recording_job;
21pub mod recording_job_request;
22pub mod recording_job_status;
23pub mod recording_plan;
24pub mod recording_request;
25pub mod recording_status;
26pub mod reports;
27pub mod shot;
28pub mod stream;
29pub mod timeline;
30pub mod viewer;
31
32/// Shared, validated editorial identity for synchronized nDisplay capture.
33/// Pulse Cluster owns the wire contract; Pixelstream authors and persists it.
34pub use pulse_capture_types::{
35    CaptureCollection, CaptureCollectionId, CaptureContext, CaptureLabel, CaptureLibraryId,
36    CollectionKind, CollectionPath, ContentRevision, EditorialContextError,
37    PixelstreamCollectionPathSegment, PixelstreamCollectionRef,
38};
39
40pub use cam_pref::*;
41pub use camera_home::*;
42pub use collection::*;
43pub use collection_membership::*;
44pub use commands::*;
45pub use control_lock::*;
46pub use frame_capture::*;
47pub use frame_capture_status::*;
48pub use frame_capture_target::*;
49pub use otio::*;
50pub use recording_job::*;
51pub use recording_job_request::*;
52pub use recording_job_status::*;
53pub use recording_plan::*;
54pub use recording_request::*;
55pub use recording_status::*;
56pub use reports::*;
57pub use shot::*;
58pub use stream::*;
59pub use timeline::*;
60pub use viewer::*;
61
62/// Force-link so the `#[myko_item]` / `#[myko_command]` / `#[myko_report]`
63/// inventory registrations are pulled into whichever binary depends on this
64/// crate. Call once at startup.
65pub fn link() {}
66
67#[cfg(test)]
68mod deser_tests {
69    use crate::{
70        collection::CollectionPathSegment,
71        commands::{JoinStream, MigrateOtioTimelines},
72        control_lock::ControlLock,
73        recording_job_request::{RecordingJobRequest, RecordingJobRequestId},
74        recording_job_status::{RecordingJobStatus, RecordingJobStatusId},
75        recording_plan::{RecordingJobAction, RecordingJobPhase, ShotEntryPlan},
76        recording_request::{RecordingKind, RecordingRequest, RecordingRequestId},
77        recording_status::{RecordingState, RecordingStatus, RecordingStatusId},
78        shot::{Shot, ShotId, ShotKind, DEFAULT_SHOT_LIBRARY_ID},
79        timeline::{ShotDirection, ShotEntry, ShotEntryMode, Timeline, TimelineId},
80        viewer::Viewer,
81        CaptureContext, CaptureLabel, CollectionPath, ContentRevision, StoredCaptureContext,
82    };
83
84    #[test]
85    fn shared_capture_context_uses_cluster_wire_contract() {
86        let context = CaptureContext {
87            collection: CollectionPath::try_from("cycle_4/moment_2".to_owned())
88                .unwrap()
89                .into(),
90            label: Some(CaptureLabel::try_from("hero orbit".to_owned()).unwrap()),
91            content_revision: Some(ContentRevision::try_from("workspace:42".to_owned()).unwrap()),
92        };
93        let value = serde_json::to_value(context).unwrap();
94        assert_eq!(value["collection"], "cycle_4/moment_2");
95        assert_eq!(value["label"], "hero orbit");
96        assert_eq!(value["contentRevision"], "workspace:42");
97    }
98
99    #[test]
100    fn stored_capture_context_is_wire_identical_to_the_bare_contract() {
101        // The newtype exists so this crate can implement Filterable for an
102        // entity field whose type another crate owns. It must be invisible on
103        // the wire: the prod event store holds ~1.5M events written before it
104        // existed, and a replay that fails here is a data-loss-grade upgrade.
105        let context = CaptureContext {
106            collection: CollectionPath::try_from("cycle_4/moment_2".to_owned())
107                .unwrap()
108                .into(),
109            label: Some(CaptureLabel::try_from("hero orbit".to_owned()).unwrap()),
110            content_revision: Some(ContentRevision::try_from("workspace:42".to_owned()).unwrap()),
111        };
112        let bare = serde_json::to_value(&context).unwrap();
113        let stored = serde_json::to_value(StoredCaptureContext(context.clone())).unwrap();
114        assert_eq!(bare, stored, "newtype changed the serialized form");
115
116        // And an event written before the newtype still reads back.
117        let replayed: StoredCaptureContext = serde_json::from_value(bare).unwrap();
118        assert_eq!(replayed.0, context);
119    }
120
121    #[test]
122    fn recording_job_status_replays_a_pre_newtype_event() {
123        // Shape taken from a persisted RecordingJobStatus event.
124        let json = r#"{"streamerId":"render-13","jobId":"job-1","captureContext":{"collection":"cycle_4/moment_2","label":"hero orbit","contentRevision":"workspace:42"},"id":"render-13"}"#;
125        let status = serde_json::from_str::<RecordingJobStatus>(json)
126            .expect("pre-newtype RecordingJobStatus must still deserialize");
127        let context = status
128            .capture_context
129            .as_ref()
130            .expect("captureContext preserved");
131        assert_eq!(
132            context.label.as_ref().map(CaptureLabel::as_str),
133            Some("hero orbit")
134        );
135        // Round-trips back to the same wire form.
136        let reserialized = serde_json::to_value(&status).unwrap();
137        assert_eq!(
138            reserialized["captureContext"]["collection"],
139            "cycle_4/moment_2"
140        );
141    }
142
143    // Exactly what the server sends over the wire (from a captured query-response).
144    #[test]
145    fn controllock_wire_deser() {
146        let j = r#"{"streamId":"s1","viewerId":"v1","clientId":"c1","id":"s1"}"#;
147        let r = serde_json::from_str::<ControlLock>(j);
148        assert!(r.is_ok(), "ControlLock deser failed: {:?}", r.err());
149    }
150
151    #[test]
152    fn viewer_wire_deser() {
153        let j = r#"{"streamId":"s1","viewerId":"v1","name":"n","color":"red","cursor":null,"clientId":"c1","id":"s1:v1"}"#;
154        let r = serde_json::from_str::<Viewer>(j);
155        assert!(r.is_ok(), "Viewer deser failed: {:?}", r.err());
156    }
157
158    #[test]
159    fn legacy_guest_join_stream_defaults_optional_identity() {
160        let j = r#"{"streamId":"s1","viewerId":"v1","name":"Anonymous Puffin","color":"red"}"#;
161        let join =
162            serde_json::from_str::<JoinStream>(j).expect("legacy JoinStream must deserialize");
163        assert_eq!(join.name, "Anonymous Puffin");
164        assert!(join.identity_issuer.is_none());
165        assert!(join.identity_subject.is_none());
166        assert!(join.avatar_url.is_none());
167    }
168
169    #[test]
170    fn shot_kind_uses_film_accurate_static_wire_term() {
171        assert_eq!(serde_json::to_value(ShotKind::Static).unwrap(), "static");
172        for legacy in ["stationary", "preset", "preset_hold"] {
173            let encoded = format!("\"{legacy}\"");
174            assert_eq!(
175                serde_json::from_str::<ShotKind>(&encoded).unwrap(),
176                ShotKind::Static
177            );
178        }
179        assert_eq!(
180            Shot::stable_id("shared", &ShotKind::Static, "Wide"),
181            "shared:shot:static:Wide"
182        );
183    }
184
185    #[test]
186    fn recording_status_uses_only_the_0_5_wire_contract() {
187        let status = RecordingStatus {
188            id: RecordingStatusId::from("render-13".to_owned()),
189            streamer_id: "render-13".to_owned(),
190            state: RecordingState::SavedToNas,
191            file_name: "capture.mp4".to_owned(),
192            nas_path: "/mnt/nas/recordings/pixelstream/capture.mkv".to_owned(),
193            dropbox_path: "recordings/pixelstream/cycle_3/dailies/capture.mp4".to_owned(),
194            error: String::new(),
195            started_at_ms: 1_785_460_000_000,
196        };
197        let value = serde_json::to_value(status).unwrap();
198        assert_eq!(value["state"], "ready_for_handoff");
199        assert_eq!(value["fileName"], "capture.mp4");
200        assert_eq!(value["startedAtMs"], 1_785_460_000_000_u64);
201        // Both destinations travel as themselves; the UI used to compose a
202        // Dropbox path out of a file name and show it for an artifact that was
203        // still only on the NAS.
204        assert_eq!(value["nasPath"], "/mnt/nas/recordings/pixelstream/capture.mkv");
205        assert_eq!(value["dropboxPath"], "recordings/pixelstream/cycle_3/dailies/capture.mp4");
206        assert!(value.get("path").is_none());
207        assert!(value.get("startedAt").is_none());
208
209        let old = r#"{
210            "id":"render-13",
211            "streamerId":"render-13",
212            "state":"done",
213            "path":"capture.mp4",
214            "startedAt":1785460000000
215        }"#;
216        assert!(serde_json::from_str::<RecordingStatus>(old).is_err());
217    }
218
219    #[test]
220    fn recording_request_direction_is_backward_compatible_and_explicit() {
221        let legacy = r#"{
222            "id":"render-13",
223            "streamerId":"render-13",
224            "active":true,
225            "rig":"Hero Push Forward"
226        }"#;
227        let legacy = serde_json::from_str::<RecordingRequest>(legacy).unwrap();
228        assert_eq!(legacy.travel_direction, None);
229        assert_eq!(legacy.shot_index, None);
230        assert_eq!(legacy.capture_kind, RecordingKind::Video);
231
232        let reverse = RecordingRequest {
233            id: RecordingRequestId::from("render-13".to_owned()),
234            streamer_id: "render-13".to_owned(),
235            active: true,
236            capture_kind: RecordingKind::Screenshot,
237            rig: "Hero Push Forward".to_owned(),
238            preset: String::new(),
239            stream_name: String::new(),
240            travel_direction: Some(ShotDirection::Reverse),
241            shot_index: Some(8),
242            take_number: 1,
243            entry_id: "entry-8".to_owned(),
244            timeline_id: String::new(),
245            timeline_name: String::new(),
246            timeline_revision: 0,
247            collection_path: Vec::new(),
248            requested_at_ms: 1,
249        };
250        let value = serde_json::to_value(reverse).unwrap();
251        assert_eq!(value["travelDirection"], "reverse");
252        assert_eq!(value["shotIndex"], 8);
253        assert_eq!(value["captureKind"], "screenshot");
254    }
255
256    #[test]
257    fn recording_job_wire_contract_is_explicit_and_resume_safe() {
258        assert_eq!(
259            serde_json::to_value(RecordingJobAction::Pause).unwrap(),
260            "pause"
261        );
262        let item = ShotEntryPlan {
263            entry_id: "entry-1".to_owned(),
264            shot_id: "shot-1".to_owned(),
265            name: "Floor Dolly".to_owned(),
266            shot_index: Some(4),
267            kind: ShotKind::Moving,
268            target_name: "Floor Dolly".to_owned(),
269            translation_speed_cm_s: 10.0,
270            rotation_speed_deg_s: 2.0,
271            hold_duration_ms: 5_000,
272            travel_duration_ms: 30_000,
273            direction: ShotDirection::Reverse,
274            next_take_number: 1,
275            open_ended: false,
276        };
277        let request = RecordingJobRequest {
278            id: RecordingJobRequestId::from("render-02".to_owned()),
279            streamer_id: "render-02".to_owned(),
280            job_id: "job-1".to_owned(),
281            command_id: "command-1".to_owned(),
282            action: RecordingJobAction::Start,
283            capture_context: None,
284            timeline_id: "timeline-1".to_owned(),
285            timeline_name: "Client selects".to_owned(),
286            timeline_revision: 4,
287            collection_id: "launch-film".to_owned(),
288            collection_path: vec![
289                CollectionPathSegment {
290                    collection_id: "autumn-campaign".to_owned(),
291                    name: "Autumn campaign".to_owned(),
292                },
293                CollectionPathSegment {
294                    collection_id: "launch-film".to_owned(),
295                    name: "Launch film".to_owned(),
296                },
297            ],
298            entries: vec![item.clone()],
299            preset_duration_ms: 0,
300            translation_speed_cm_s: 0.0,
301            rotation_speed_deg_s: 0.0,
302            requested_at_ms: 10,
303        };
304        let value = serde_json::to_value(request).unwrap();
305        assert_eq!(value["action"], "start");
306        assert_eq!(value["timelineId"], "timeline-1");
307        assert_eq!(value["timelineName"], "Client selects");
308        assert_eq!(value["timelineRevision"], 4);
309        assert!(value.get("shotListId").is_none());
310        assert_eq!(value["collectionId"], "launch-film");
311        assert_eq!(value["collectionPath"][0]["name"], "Autumn campaign");
312        assert_eq!(value["collectionPath"][1]["name"], "Launch film");
313        assert_eq!(value["entries"][0]["translationSpeedCmS"], 10.0);
314        assert_eq!(value["entries"][0]["rotationSpeedDegS"], 2.0);
315        assert_eq!(value["entries"][0]["direction"], "reverse");
316        assert_eq!(value["entries"][0]["shotIndex"], 4);
317
318        let mut status = RecordingJobStatus {
319            id: RecordingJobStatusId::from("render-02".to_owned()),
320            streamer_id: "render-02".to_owned(),
321            job_id: "job-1".to_owned(),
322            capture_context: None,
323            timeline_id: "timeline-1".to_owned(),
324            timeline_name: "Client selects".to_owned(),
325            timeline_revision: 4,
326            collection_id: "launch-film".to_owned(),
327            collection_path: vec![CollectionPathSegment {
328                collection_id: "launch-film".to_owned(),
329                name: "Launch film".to_owned(),
330            }],
331            phase: RecordingJobPhase::Paused,
332            pause_requested: false,
333            entries: vec![item],
334            index: 0,
335            completed: 0,
336            error: "resume required".to_owned(),
337            updated_at_ms: 11,
338            elapsed_ms: 4_000,
339            estimated_total_ms: 90_000,
340            estimated_remaining_ms: 86_000,
341            takes: Vec::new(),
342            started_at_ms: 1,
343        };
344        assert!(status.can_resume());
345        assert_eq!(status.resume_progress(), (1, 1));
346        assert_eq!(serde_json::to_value(&status).unwrap()["phase"], "paused");
347
348        status.phase = RecordingJobPhase::Canceled;
349        assert!(!status.can_resume());
350
351        status.phase = RecordingJobPhase::Complete;
352        status.error = "1 take rejected; the job continued".to_owned();
353        assert!(status.can_resume());
354        assert_eq!(
355            status.summary(),
356            "Recording complete with warnings · 0 of 1 takes durable on NAS · 1 take rejected; the job continued"
357        );
358    }
359
360    #[test]
361    fn timeline_mode_migrates_legacy_enabled_values() {
362        assert_eq!(
363            serde_json::from_str::<ShotEntryMode>("true").unwrap(),
364            ShotEntryMode::Forward
365        );
366        assert_eq!(
367            serde_json::from_str::<ShotEntryMode>("false").unwrap(),
368            ShotEntryMode::Excluded
369        );
370        assert_eq!(
371            serde_json::from_str::<ShotEntryMode>(r#""both""#).unwrap(),
372            ShotEntryMode::Both
373        );
374
375        let legacy_shot = r#"{
376            "id":"render-02:moving:Floor Dolly",
377            "streamerId":"render-02",
378            "name":"Floor Dolly",
379            "kind":"moving",
380            "targetName":"Floor Dolly",
381            "translationSpeedCmS":10.0,
382            "rotationSpeedDegS":2.0,
383            "holdDurationMs":5000,
384            "batchMode":"excluded",
385            "sortOrder":0
386        }"#;
387        let shot = serde_json::from_str::<Shot>(legacy_shot).unwrap();
388        assert_eq!(shot.effective_library_id(), "shared");
389        assert_eq!(shot.default_entry_mode, ShotEntryMode::Excluded);
390        assert_eq!(shot.shot_index, 0);
391        let shot_wire = serde_json::to_value(shot).unwrap();
392        assert_eq!(shot_wire["sortOrder"], 0);
393        assert!(shot_wire.get("shotIndex").is_none());
394
395        let legacy_plan = r#"{
396            "shotId":"shot-1",
397            "name":"Floor Dolly",
398            "kind":"moving",
399            "targetName":"Floor Dolly",
400            "translationSpeedCmS":10.0,
401            "rotationSpeedDegS":2.0,
402            "holdDurationMs":5000
403        }"#;
404        let legacy_plan = serde_json::from_str::<ShotEntryPlan>(legacy_plan).unwrap();
405        assert_eq!(legacy_plan.direction, ShotDirection::Forward);
406        assert_eq!(legacy_plan.shot_index, None);
407    }
408
409    #[test]
410    fn legacy_clips_without_overrides_remain_compatible() {
411        let mut timeline = Timeline {
412            id: TimelineId::from(Timeline::legacy_default_id("render-02")),
413            library_id: "shared".to_owned(),
414            streamer_id: "render-02".to_owned(),
415            name: "Client selects".to_owned(),
416            revision: 3,
417            entries: vec![ShotEntry {
418                shot_id: "shot-a".to_owned(),
419                direction: ShotEntryMode::Both,
420                ..Default::default()
421            }],
422            sort_order: 0,
423        };
424
425        timeline.normalize_entries();
426        assert_eq!(timeline.entries.len(), 2);
427        assert_eq!(timeline.capture_count(), 2);
428        assert_eq!(timeline.next_revision(), 4);
429        assert!(timeline
430            .entries
431            .iter()
432            .all(|entry| !entry.entry_id.is_empty()));
433        assert_eq!(timeline.entries[0].direction, ShotEntryMode::Forward);
434        assert_eq!(timeline.entries[1].direction, ShotEntryMode::Reverse);
435
436        timeline.add_entry("shot-b", ShotEntryMode::Forward);
437
438        let first_entry_id = timeline.entries[0].entry_id.clone();
439        timeline.remove_entry(&first_entry_id);
440        assert_eq!(timeline.entries.len(), 2);
441
442        let value = serde_json::to_value(timeline).unwrap();
443        assert_eq!(value["entries"][0]["shotId"], "shot-a");
444        assert!(value["entries"][0].get("translationSpeedCmS").is_none());
445        assert!(value["entries"][0].get("rotationSpeedDegS").is_none());
446        assert!(value.get("clips").is_none());
447        assert!(value["entries"][0].get("cueId").is_none());
448        assert!(value["entries"][0].get("clipId").is_none());
449        assert!(value["entries"][0].get("mode").is_none());
450    }
451
452    #[test]
453    fn the_same_shot_has_independent_parameters_in_each_timeline() {
454        let shot = Shot {
455            id: ShotId::from("shared:shot:moving:hero"),
456            library_id: DEFAULT_SHOT_LIBRARY_ID.to_owned(),
457            streamer_id: String::new(),
458            name: "Hero".to_owned(),
459            kind: ShotKind::Moving,
460            target_name: "Hero".to_owned(),
461            translation_speed_cm_s: 10.0,
462            rotation_speed_deg_s: 2.0,
463            hold_duration_ms: 5_000,
464            travel_duration_ms: 30_000,
465            default_entry_mode: ShotEntryMode::Forward,
466            shot_index: 0,
467        };
468        let mut fast = ShotEntry::from_shot(&shot, ShotEntryMode::Forward);
469        let mut slow = ShotEntry::from_shot(&shot, ShotEntryMode::Forward);
470        fast.translation_speed_cm_s = Some(20.0);
471        fast.travel_duration_ms = Some(15_000);
472        slow.translation_speed_cm_s = Some(5.0);
473        slow.travel_duration_ms = Some(60_000);
474
475        assert_eq!(fast.resolved_shot(&shot).translation_speed_cm_s, 20.0);
476        assert_eq!(slow.resolved_shot(&shot).translation_speed_cm_s, 5.0);
477        assert_eq!(fast.resolved_shot(&shot).travel_duration_ms, 15_000);
478        assert_eq!(slow.resolved_shot(&shot).travel_duration_ms, 60_000);
479        assert_eq!(shot.translation_speed_cm_s, 10.0);
480    }
481
482    #[test]
483    fn timeline_normalizes_membership_without_persisting_a_second_index() {
484        let legacy = r#"{
485            "id":"render-02:timeline:legacy",
486            "streamerId":"render-02",
487            "name":"Legacy",
488            "version":0,
489            "entries":[
490                {"shotId":"shot-b","mode":"forward"},
491                {"shotId":"shot-a","mode":"reverse"}
492            ],
493            "sortOrder":0
494        }"#;
495        let mut timeline: Timeline = serde_json::from_str(legacy).unwrap();
496        timeline.normalize_entries();
497        assert_eq!(timeline.entries[0].shot_id, "shot-b");
498        assert_eq!(timeline.entries[1].shot_id, "shot-a");
499        assert!(serde_json::to_value(timeline).unwrap()["entries"][0]
500            .get("index")
501            .is_none());
502    }
503
504    #[test]
505    fn timeline_migration_accepts_the_myko_transaction_envelope() {
506        serde_json::from_str::<MigrateOtioTimelines>(r#"{"tx":"migration-tx"}"#)
507            .expect("migration command must accept Myko's map-shaped envelope");
508    }
509}
510
511// myko 6 requires every queryable field's type to implement `Filterable`.
512// Plain enums get value equality (`Eq`/`In` filters work as an operator would
513// expect); payload structs with no query-meaningful equality take the opaque
514// escape hatch, which renders their query field structurally absent.
515myko::impl_filterable_eq!(
516    crate::recording_plan::RecordingJobAction,
517    crate::recording_plan::RecordingJobPhase,
518    crate::recording_request::RecordingKind,
519    crate::recording_status::RecordingState,
520    crate::shot::ShotKind,
521    crate::timeline::ShotDirection,
522    crate::timeline::ShotEntryMode,
523    crate::frame_capture::FrameCapturePhase,
524);
525
526myko::impl_filterable_opaque!(
527    crate::frame_capture::FrameCaptureTarget,
528    StoredCaptureContext,
529);
530
531/// `CaptureContext` as an entity field.
532///
533/// Every field of a `#[myko_item]` needs `Filterable`, and this crate cannot
534/// implement it for `CaptureContext` — pulse-capture-types owns that type and
535/// the orphan rule forbids the impl. A newtype this crate does own can carry
536/// it, and `Unfilterable` is the right filter anyway: frozen editorial
537/// identity is payload, never a query axis.
538///
539/// `#[serde(transparent)]` means the wire form is exactly the bare contract
540/// type, so persisted events and TS bindings are unchanged — this exists for
541/// the type system, not for the format.
542#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize, myko::TS)]
543#[serde(transparent)]
544#[ts(type = "unknown")]
545pub struct StoredCaptureContext(pub CaptureContext);
546
547impl From<CaptureContext> for StoredCaptureContext {
548    fn from(context: CaptureContext) -> Self {
549        Self(context)
550    }
551}
552
553impl From<StoredCaptureContext> for CaptureContext {
554    fn from(stored: StoredCaptureContext) -> Self {
555        stored.0
556    }
557}
558
559impl std::ops::Deref for StoredCaptureContext {
560    type Target = CaptureContext;
561
562    fn deref(&self) -> &Self::Target {
563        &self.0
564    }
565}
pulse_pixelstream_types/lib.rs

pulse_pixelstream_types/
lib.rs
