Cameras
Video from USB webcams on every platform and from CSI cameras on the Raspberry Pi, with a timing file that has one row per frame.
Each camera runs in its own module instance with its own window, so several cameras can record at once. A USB webcam with a built-in microphone can record its audio into the same file.
Getting started
- Connect the cameraUSB, or the ribbon cable on a Raspberry Pi.
- Enable the moduleCheck Cameras in the Modules menu, or Cameras-CSI on a Raspberry Pi. Detected cameras appear in the Devices panel.
- Connect the cameraClick its entry in the Devices panel. The indicator turns green and the camera’s window opens with a live preview. Click again to disconnect.
- Adjust settingsView > Camera Settings… in the camera window.
- RecordStart a session and click Record.
The camera window
The preview is scaled down and updated less often than the recording, to save processor time. It does not affect what is recorded.
The metrics panel shows the frame rate the camera is delivering, the frame rate being written to disk, the preview rate and the audio state. If the recorded rate falls below the rate you set, the computer or the USB bus is not keeping up. See Performance.
What is written
For each trial, a video file and a timing CSV in a folder named after the camera.
| Camera | Folder | Video |
|---|---|---|
| USB | {session_dir}/Cameras/{camera id}/ | {token}_CAM_trial001_{camera}.mp4, H.264, with AAC audio when enabled |
| CSI | {session_dir}/picam0/ | {token}_CSI_trial001_{camera}.avi, MJPEG |
The timing CSV has the same name with _timing.csv in place of the extension. The video is encoded in software with libx264 for USB cameras and OpenCV’s MJPEG writer for CSI cameras.
Timing CSV, 9 columns
| Column | Description |
|---|---|
trial | Trial number |
module | USBCameras or CSICameras |
device_id | The camera |
label | The trial label, if any |
record_time_unix | Host wall-clock time when the frame was read from the camera driver, six decimals |
record_time_mono | Host monotonic clock at the same instant, nine decimals |
frame_index | Frame number in the video file, from 1 |
sensor_timestamp_ns | The sensor’s exposure timestamp in nanoseconds. CSI cameras only, 0 for USB |
video_pts | Presentation timestamp of the frame in the container |
To find the frame at a moment from another module, take that row’s record_time_mono, find the nearest record_time_mono in the timing file, and seek to its frame_index. Synchronization has the code.
USB and CSI cameras
| Feature | USB | CSI |
|---|---|---|
| Platform | Windows, macOS, Linux, Raspberry Pi | Raspberry Pi only |
| Cameras | Any UVC webcam | Raspberry Pi camera modules and other libcamera sensors, including the IMX296 global-shutter camera |
| Sensor timestamps | No | Yes, sensor_timestamp_ns |
| Audio | From the camera’s own microphone, optional | No |
| Video | MP4, H.264 | AVI, MJPEG |
| Hot-plug | Yes | No. Connect with the Pi powered off |
The frame rate a USB webcam delivers depends on the light. Many webcams halve their rate in dim rooms.
Settings
View > Camera Settings… in the camera window.
| Setting | Default | Choices |
|---|---|---|
| Resolution | 640 × 480 | 320 × 240, 640 × 480, 800 × 600, 1280 × 720, 1920 × 1080 |
| Frame Rate | 30 | 10, 15, 24, 30, 60 |
| Preview Size | 1/4 | Scale of the preview relative to the recording |
| Preview Update Rate | Every 4th frame | How many recorded frames pass between preview updates |
| Audio | On when the camera has a microphone | Shown only for cameras with a microphone |
| Sample Rate | 48000 | 44100, 48000, 96000 |
A higher resolution or frame rate means larger files and more processor time. The camera may not support every combination; the metrics panel shows what it delivers.
Performance
Cameras on the same USB controller share its bandwidth. If the delivered frame rate drops when you add a camera, move one to a port on a different controller, which on a desktop usually means the other side of the machine or a separate USB card.
Record to an SSD. On a Raspberry Pi, record to a USB SSD rather than the microSD card. File size depends on resolution, frame rate and the scene, so check a short test recording before a long session.
Troubleshooting
The camera is not detected
Check the cable and whether another program has the camera open. On a Raspberry Pi, libcamera-hello —list-cameras lists CSI cameras. On Linux, v4l2-ctl —list-devices lists USB cameras. On macOS and Windows, check that RSLogger has permission to use the camera.
Frames are dropped or the rate is low
Lower the frame rate first, then the resolution. Improve the lighting. Record to faster storage. Try another USB port or controller.
The preview lags
Reduce the preview size or the preview update rate. Neither affects the recording.
Audio drifts against the video
Set the frame rate to what the camera delivers, as shown in the metrics panel, rather than a higher rate it cannot sustain.