Recording Multiple Subjects

If you're capturing several subjects in a row without moving the cameras, you don't need to repeat camera calibration for each one. Creating a new session from a previous, calibrated session carries over its camera calibration — only the new subject needs to be calibrated before you can start recording.

Full working example

See examples/scripts — the activity_recording script for each language loops through subjects this way, offering to start a new session with the same camera setup after each subject's activities are recorded.

When to Use This

• Cameras must stay in the same physical position as the source session. If you need to reposition any camera, recalibrate instead and start from a fresh session.
• The source session must have already completed camera calibration — that's what gets carried over.

Creating a New Session

Swift

let newSession = try await client.newSession(from: previousSession)

TypeScript

const newSession = await client.newSessionFromSession(previousSession);

Python

new_session = client.new_session_from_session(previous_session)

This returns a brand new, independent Session — the previous session is untouched and remains usable.

What Carries Over

	Carried over?
Camera calibration	Yes
Session configuration (framerate, OpenSim model, etc.)	Yes
Camera connection — no QR scan needed	Yes
Subject calibration	No — calibrate the new subject before recording

Since cameras are already paired and calibrated, skip straight to Subject Calibration for the new subject — there's no need to reconnect cameras or repeat checkerboard calibration.

Looping Over Subjects

Swift

repeat {
    let subject = pickOrCreateSubject()
    try await client.calibrateSubject(subject, in: session, statusUpdate: callback)

    // record one or more activities for this subject...

    guard confirm("Record another subject with the same camera setup?") else {
        break
    }
    session = try await client.newSession(from: session)
} while true

TypeScript

for (;;) {
  const subject = pickOrCreateSubject();
  await client.calibrateSubject(subject, session, callback);

  // record one or more activities for this subject...

  if (!(await confirm("Record another subject with the same camera setup?"))) {
    break;
  }
  session = await client.newSessionFromSession(session);
}

Python

while True:
    subject = pick_or_create_subject()
    client.calibrate_subject(subject, session, callback)

    # record one or more activities for this subject...

    if not confirm("Record another subject with the same camera setup?"):
        break
    session = client.new_session_from_session(session)

Going Back to a Subject

Subjects rarely arrive in a neat order — someone steps out, someone needs a second attempt. switchSubject moves to whoever is next, in any order, and takes the cameras with them. If that subject already has a session whose camera calibration and static pose are both still good, the same session comes back and their pose is not repeated.

Swift

session = try await client.switchSubject(to: subject, in: session)

TypeScript

session = await client.switchSubject(subject, session);

Python

session = client.switch_subject(subject, session)

Use the session it returns from then on: it may be one that already existed, the one you passed in, or a new one.

Record nobody in the calibrated session itself

Keep the session you calibrated the cameras in for the checkerboard alone, and give every subject — the first one included — a session of their own through switchSubject.

A subject recorded directly in the calibration session cannot be returned to. Coming back to them starts an empty session instead, with no static pose in it, and the first recording there fails immediately.

Swift

var session = try await client.createSession()
try await client.calibrateCamera(session, checkerboardDetails: board) { _ in }

for subject in subjects {
    session = try await client.switchSubject(to: subject, in: session)
    try await client.calibrateSubject(subject, in: session) { _ in }
    // record their activities...
}

// Back to the first subject — the session they were already in, no pose to repeat.
session = try await client.switchSubject(to: subjects[0], in: session)

TypeScript

let session = await client.createSession();
await client.calibrateCamera(session, board, () => {});

for (const subject of subjects) {
  session = await client.switchSubject(subject, session);
  await client.calibrateSubject(subject, session, () => {});
  // record their activities...
}

// Back to the first subject — the session they were already in, no pose to repeat.
session = await client.switchSubject(subjects[0], session);

Python

session = client.create_session()
client.calibrate_camera(session, board, lambda status: None)

for subject in subjects:
    session = client.switch_subject(subject, session)
    client.calibrate_subject(subject, session, lambda status: None)
    # record their activities...

# Back to the first subject — the session they were already in, no pose to repeat.
session = client.switch_subject(subjects[0], session)

Fetching an earlier session by its id does not do this. Reading a session tells the cameras nothing — they carry on polling the one they were last sent to, and a recording started elsewhere reaches nobody.

Troubleshooting

Request fails or session not found:

• Confirm the source session has completed camera calibration — sessions that haven't been calibrated yet can't be used as the source for this call
• Check network connectivity, as with any other session operation

Next Steps

With the new session created, proceed to Subject Calibration for the next subject.