MAKIINASDK

GuidesSensors and recordingRecord demonstrations

Record demonstrations

Capture sessions with every camera frame, command and state for learning, from the console or from your code, and see what a dataset made from them holds.

A recording keeps everything that happened in a session: every frame of every camera stream, every command you sent and every state the robot reported, exactly as they travelled over the network. You record first and decide later how to turn it into training data. This guide shows how to record from the console and from Python, where the files go, and what the dataset converter makes of them.

Record from the console

In a session with a fleet robot, click the record button in the top bar. The recording card opens.

Console

Click Start to begin and Stop to end. Mark demo starts the next demonstration within the same recording. Subtask id labels the task you are demonstrating, and Save to is the folder the recordings go in.

The Recording popover while recording: Start, Stop, Mark demo, Subtask id, Save to and convert to a dataset on stop.
Python

The console's buttons set the same flags your code can set:

Python
robot.recording.start(subtask=2)
robot.recording.mark_demo()
robot.recording.stop()

While recording, the button in the top bar turns red and shows the elapsed time. The console records with its own recorder process; you do not need to start anything else.

convert to a dataset on stop and Convert last run the dataset converter on a recording. The converter is not part of the SDK kit, so in a kit the console answers converter needs a core checkout (ml/) and keeps the recording as it is. The recordings are complete either way, and the converter can turn them into datasets later (Turn a recording into a dataset).

Record from Python

The robot records nothing itself. A recorder process on your PC listens to a copy of the session's traffic and writes it to disk while the recording flag is on. Start one, and tell your session where it listens:

Shell
.venv\Scripts\python.exe -m makiina.recorder --out recordings     # Windows
.venv/bin/python -m makiina.recorder --out recordings             # Linux
Python
import os
os.environ["MAKIINA_TEE_PORT"] = "17999"        # before connecting

from makiina.robot import Robot

robot = Robot.connect("acme-robot-02")
robot.recording.start(subtask=0)                # a session opens on disk
# ... demonstrate ...
robot.recording.mark_demo()                     # next demonstration
# ... demonstrate ...
robot.recording.stop()                          # the recorder closes the session
robot.disconnect()

The recorder listens on port 17999 by default; MAKIINA_TEE_PORT makes your session send its copy there. Leave the recorder running between recordings; it waits until the flag says record.

Mark what you are doing

The flags you set become the structure of the dataset:

CallEffect
start(subtask=None)recording on; both arms count as engaged
mark_demo()the next frames belong to a new demonstration
set_subtask(subtask)the task label of the frames from now on
set_trackings(trackings)whether each arm is engaged, [right, left]; a span with both off splits episodes
stop()recording off; the recorder closes the files

With a leader and follower rig or scripted teleoperation, drive the same flags from your loop.

Find the files

Each recording is a folder named after the moment it started:

Text
recordings/
  2026-09-29_14-42-17/
    packets.mkrec        every packet of the session, with timestamps
    meta.json            robot model, streams, camera calibration, counts

packets.mkrec is lossless and compact: the video is kept as it arrived, not decoded. It is the master copy; keep it even after you convert.

Turn a recording into a dataset

The dataset converter is not part of the SDK kit: ask MAKIINA for it at sales@makiina.com. It decodes the video and writes one image per stream and one label file per frame, at a fixed rate:

Shell
.venv\Scripts\python.exe ml\dataset_from_session.py recordings\2026-09-29_14-42-17 --out recordings-datasets     # Windows
.venv/bin/python ml/dataset_from_session.py recordings/2026-09-29_14-42-17 --out recordings-datasets             # Linux
Text
recordings-datasets/2026-09-29_14-42-17/
  images/stereo_cam_left/frame_000000.jpg
  images/stereo_cam_right/frame_000000.jpg
  images/stereo_cam_left_fovea/...  images/gripper_cam_left/...
  labels/frame_000000.json

Each label holds the commanded joint positions and the gripper poses they give, the gripper triggers, the gaze, the engagement flags, the demo counter, the subtask and the time. The converter starts at the moment you started recording and keeps 30 frames per second unless you pass --fps; --streams limits it to the streams you name.

A dataset has the same streams in both head camera modes. In a recording made in full resolution, stereo_cam_left and stereo_cam_right are the full 2304 x 1296 pictures, and the converter cuts the fovea images out of them at each frame's gaze, the same window the live API gives (See what the robot sees).

The converter decodes the video with ffmpeg, which must be on your PATH.

Record someone else's session

A recorder can also capture a session that another program on the same computer owns, without taking the session over, when that program sends a copy of its traffic to port 17999, as a script started with MAKIINA_TEE_PORT does. The recorder then follows the recording flags of that session. To start and stop it yourself while the operator works, send it an override from Python:

Python
from makiina.recorder import RecorderControl

rec = RecorderControl()         # the recorder on port 17999
rec.start(subtask=0)
rec.mark_demo()
rec.stop()
rec.release()                   # the session's own flags rule again

Use LeRobot

A plugin adapts a MAKIINA robot to the Hugging Face LeRobot Robot interface, for recording LeRobot datasets and running policies. It is not part of the SDK kit: ask MAKIINA for it at sales@makiina.com. It installs with pip into a Python environment that has the SDK and LeRobot:

Shell
python -m pip install -e <the plugin folder>
Python
from lerobot_robot_makiina import MakiinaRobot, MakiinaRobotConfig

robot = MakiinaRobot(MakiinaRobotConfig(robot_name="acme-robot-02"))
robot.connect()
obs = robot.get_observation()               # joints, gripper poses, gaze, images
robot.send_action({"J01-R.pos": 0.1})
robot.disconnect()

The image keys follow the robot's streams; restrict them with camera_names.