Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions crates/session/src/doc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,18 @@ impl SessionDoc {
read_records(&self.doc.get_map(LANES), read_lane)
}

/// Every marker.
#[must_use]
pub fn markers(&self) -> BTreeMap<MarkId, Marker> {
read_records(&self.doc.get_map(MARKERS), read_marker)
}

/// Every region.
#[must_use]
pub fn regions(&self) -> BTreeMap<MarkId, Region> {
read_records(&self.doc.get_map(REGIONS), read_region)
}

/// Every item.
#[must_use]
pub fn items(&self) -> BTreeMap<ItemId, Item> {
Expand Down
62 changes: 60 additions & 2 deletions crates/session/src/service.rs
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,9 @@ pub enum Request {
Remove { name: String },
/// Every lane, and every item with other extensions' payloads nulled.
ReadTimeline,
/// The song's structure: the tempo map, markers and regions, which
/// every extension reads (a follower resolves musical time with it).
ReadStructure,
/// Puts a lane it owns.
PutLane { id: LaneId, lane: Lane },
/// Removes a lane it owns, and the items on it it owns. Another
Expand Down Expand Up @@ -121,6 +124,47 @@ pub struct TempoChange {
pub bpm: f64,
/// The new meter, when it changes here.
pub meter: Option<Meter>,
/// How the tempo moves from here to the next change: REAPER's shape
/// (`None` or 1 holds, 0 is linear, 5 bezier); see `time::TempoShape`.
pub shape: Option<i32>,
/// A bezier shape's tension.
pub tension: Option<f64>,
}

impl TempoMapData {
/// `tempo` as plain data, ramps included.
#[must_use]
pub fn of(tempo: &TempoMap) -> Self {
let meter = tempo.default_meter();
Self {
default_bpm: tempo.default_bpm(),
numerator: meter.numerator,
denominator: meter.denominator,
points: tempo
.points()
.iter()
.map(|p| TempoChange {
seconds: p.position_seconds(),
bpm: p.bpm,
meter: p.time_signature.map(|t| Meter {
numerator: t.numerator,
denominator: t.denominator,
}),
shape: p.shape,
tension: p.bezier_tension,
})
.collect(),
}
}

/// The tempo map this describes.
///
/// # Errors
///
/// A tempo that is not a positive number, or a meter with a zero.
pub fn to_tempo_map(&self) -> Result<TempoMap, ServiceError> {
tempo_map(self)
}
}

/// The answer.
Expand All @@ -133,6 +177,11 @@ pub enum Response {
lanes: BTreeMap<LaneId, Lane>,
items: BTreeMap<ItemId, Item>,
},
Structure {
tempo: TempoMapData,
markers: BTreeMap<MarkId, Marker>,
regions: BTreeMap<MarkId, Region>,
},
}

/// Why a request was not done.
Expand Down Expand Up @@ -177,7 +226,7 @@ impl From<loro::LoroError> for ServiceError {
#[must_use]
pub const fn action_for(request: &Request) -> &'static str {
match request {
Request::ReadData | Request::ReadTimeline => READ,
Request::ReadData | Request::ReadTimeline | Request::ReadStructure => READ,
Request::SetTempo { .. }
| Request::PutMarker { .. }
| Request::PutRegion { .. }
Expand Down Expand Up @@ -265,6 +314,12 @@ pub fn handle(
request: Request,
) -> Result<Response, ServiceError> {
match request {
// Everyone reads the structure; no grant needed.
Request::ReadStructure => Ok(Response::Structure {
tempo: TempoMapData::of(&doc.tempo()),
markers: doc.markers(),
regions: doc.regions(),
}),
Request::ReadTimeline
| Request::PutLane { .. }
| Request::RemoveLane { .. }
Expand Down Expand Up @@ -483,7 +538,10 @@ fn tempo_map(data: &TempoMapData) -> Result<TempoMap, ServiceError> {
Some(m) => Some(meter(m.numerator, m.denominator)?),
None => None,
};
points.push(TempoMap::point(change.seconds, change.bpm, meter));
let mut point = TempoMap::point(change.seconds, change.bpm, meter);
point.shape = change.shape;
point.bezier_tension = change.tension;
points.push(point);
}
Ok(TempoMap::new(
data.default_bpm,
Expand Down
71 changes: 71 additions & 0 deletions crates/session/tests/session/service.rs
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,8 @@ fn the_song_structure_needs_a_grant() {
numerator: 6,
denominator: 8,
}),
shape: None,
tension: None,
}],
},
};
Expand All @@ -268,3 +270,72 @@ fn the_song_structure_needs_a_grant() {
};
assert!(refused(handle(&doc, &ext("keyflow"), granted, bad)));
}

#[test]
fn everyone_reads_the_structure_with_its_ramps() {
let doc = studio();
let granted = Grants { structure: true };
// A ramp from 60 to 120 BPM over 10 s (shape 0: linear), then held.
let tempo = TempoMapData {
default_bpm: 60.0,
numerator: 4,
denominator: 4,
points: vec![
TempoChange {
seconds: 0.0,
bpm: 60.0,
meter: None,
shape: Some(0),
tension: None,
},
TempoChange {
seconds: 10.0,
bpm: 120.0,
meter: None,
shape: None,
tension: None,
},
],
};
handle(
&doc,
&ext("keyflow"),
granted,
Request::SetTempo {
tempo: tempo.clone(),
},
)
.unwrap();
handle(
&doc,
&ext("keyflow"),
granted,
Request::PutMarker {
id: MarkId::from("drop"),
marker: session::Marker {
at: Time::QuarterNotes(32.0),
name: "Drop".into(),
color: None,
ruler: None,
},
},
)
.unwrap();
// Ignition, granted nothing, reads it.
let Response::Structure {
tempo: read,
markers,
regions,
} = ask(&doc, "ignition", Request::ReadStructure).unwrap()
else {
panic!("not the structure")
};
assert_eq!(read, tempo);
assert_eq!(markers[&MarkId::from("drop")].name, "Drop");
assert!(regions.is_empty());
// The ramp is kept: seconds resolve as the session's own map does.
let map = read.to_tempo_map().unwrap();
let qn = Time::Seconds(7.25).quarter_notes(&map);
assert!((qn - Time::Seconds(7.25).quarter_notes(&doc.tempo())).abs() < 1e-12);
assert!((map.bpm_at(11.0) - 120.0).abs() < 1e-12);
}
82 changes: 54 additions & 28 deletions docs/design/session.md
Original file line number Diff line number Diff line change
Expand Up @@ -686,34 +686,60 @@ session as an Architect document, kept in step through Architect's sync.

## 9. Before Studio, Keyflow or Ignition can share a session

In order:

1. **The `fts.session` service wrapper**, built: `session::host` (feature
`vox`), `SessionService::ask(doc, request)` over `service::handle`.
- The caller is the call's principal. An extension's call
(`Principal::Extension`) names its namespace; any other principal is
refused.
- The action is the permission engine's answer on `doc/<id>`: `read`,
`write`, or `structure` for tempo, markers and regions.
- The gate checks `read` before decoding (`doc/**`); the handler
checks the exact document.
- The host and its gate ask the same engine, the org's one, which
answers a share link's guest by what the link grants. A read-only
link reads and every edit is refused, with no guest code path.
2. **A host that holds the document**, for the first consumer, which
should be Keyflow, the smallest: a chart with a tempo map and no
engine. Its app opens a `.session` as a `DocFile` of `kind()`, syncs it
with `OrgSyncs` (or a share link), and serves `fts.session` to its
chart view. Keyflow's chart moves into `keyflow`'s `chart` text,
bound with `TextBinding`.
3. **The shared clock** (§7.5), so a follower on another machine follows
for real. Until then playheads across machines are as good as the
process clocks' agreement (unrelated).
4. **Ignition** on the same session: its cue lists as lanes and items,
following the transport with `Tracker`, through the service.
5. **Studio**: rename its `session` crate to `session-app`, then the
migration of §5.3, which is the long pole (the DAW's data as extension
data, the live document's 4 → 5 migration, the file).
Built (2026-11-18), in order:

1. **`fts.session` over vox** (`session::host`, session#181). The caller
is the call's principal; what it may do is the permission engine's
answer on `doc/<id>` (`read`, `write`, `structure`). The host and its
gate ask the org's one engine, so a read-only share link's guest reads
and is refused writes, with no guest code path.
2. **`fts.session` as an Architect extension service**
(`session::extension`, session#182). The provider's actions answer for
`cx.caller` (Architect's newer code: the `runtime-compositor-keyflow`
pin), one method per action, so Architect's effect check holds a guest
to `read`. Ids are transparent on the wire, so a timeline crosses JSON.
3. **Keyflow as the first host** (keyflow#85: `keyflow-session`):
- a chart is Keyflow's `chart` text entry in a `.session` `DocFile`,
synced through Architect's sync and bound to an editor with
`TextBinding`;
- `Provider` serves `fts.session`;
- `ChartSource` is the chart pane's state, a document (the chart
alone) or a session.

Found: Architect's `SyncedDoc` does not persist what it receives
(`apply_remote`, not `apply_remote_durable`); `ChartSession::save`
writes it.
4. **The shared clock** (`session::clock`, session#183): the host
serves `now()`, a peer's `SharedClock` estimates it, `play_state`
stamps `PlayState::at_ms` in it.
- **Two processes on one machine:** playhead error max 168 µs
(exact truth).
- **Two machines on a LAN:** the estimate is within ±0.92 ms (half
the round trip); wall clocks cannot judge it tighter.
5. **Reading the structure** (`ReadStructure`, ramps included,
session#184), and **Ignition on the session** (ignition#16:
`ignition-session`):
- cue lists as lanes and timed items at their bars, untimed cues and
list settings as Ignition's data;
- read back in GO order for `CuePlayer`;
- followed from the transport by `CueFollower`.

Still missing, in the order to do them:

1. **The chart view on the session**: `feat/runtime-chart` reads its chart
through `ChartSource` (four lines, keyflow#85 lists them) and the app
hosting Keyflow registers the provider's actions. Needs that branch's
Architect pin.
2. **Architect**:
- `SyncedDoc` applying remote updates durably;
- the shared clock moved into the presence driver;
- a tag the fleet can pin with `cx.caller`.
3. **Network sync** in a real host: the org driver (`OrgSyncs`) or a share
link's iroh dial, which the tests stand in for with the in-process
transport.
4. **Ignition's extension** asking through its host, and DMX output taken
from `CueFollower`.
5. **Studio**: rename its `session` crate to `session-app`, then §5.3.

## 10. Not sure of

Expand Down
Loading