Cameras

Add a camera from Python

Call add_camera on a LiveStream. It needs ffmpeg on PATH. Use the same API key for the camera as for its stream.

from kymoscope import LiveStream

with LiveStream(API_KEY, "Rig A", state_path="kymoscope-state.json") as stream:
    stream.add_camera("Front", "video=Integrated Camera", input_format="dshow")      # a webcam on Windows
    stream.add_camera("Bay", "/dev/video0", input_format="v4l2", size="1280x720")    # a webcam on Linux
    stream.add_camera("Door", "rtsp://user:pass@10.0.0.7/stream1", copy=True)        # an H.264 IP camera, as is
    stream.add_camera("Test", "testsrc=size=1280x720:rate=30", input_format="lavfi") # a test pattern
    while True:
        stream.send(...)    # keep sending (or call stream.tick()): the cameras heartbeat with the stream

• ffmpeg re-encodes to H.264 with a keyframe every 2 seconds. With copy=True the keyframe interval is the camera’s own.
• Frames are stamped with time.time(). If your data uses Unix times too, the sync is Exact.
• Video goes out only while someone watches the camera. A new viewer starts at the next keyframe.
• The camera registers and heartbeats with its stream, and closing the stream stops it. Keep calling send or tick.
• Credentials in a camera URL (rtsp://user:pass@host/…) are on ffmpeg’s command line, so other users of the same machine can read them in the process list. Kymoscope hides them (rtsp://***@host) in everything it prints. Use a camera account that can only view the stream, on a machine nobody else uses.

Add a camera from a browser

A browser that can encode H.264 with WebCodecs is needed. Chrome and Edge can. The page tells you when your browser can’t.

1. Open /camera in the Kymoscope app on the machine with the camera.
2. Choose one of your live data streams, the camera device, a quality and a name. 720p at 30 fps is the default and uses about 2 Mbit/s. 1080p at 30 fps uses about 4 Mbit/s.
3. Paste the API key that publishes that stream and start. The browser keeps the key only if you tick “Remember this key on this device”.

Watch a camera

Open a stream and its cameras open with it, with nothing extra to type. They use the same key material as the stream: the project key, the same password or API key, or your own browsers. In the stream browser and the Datasets drawer, cameras are listed under their stream. A camera has no checkbox because it plots no data. Its “Add Camera panel” button puts it in the worksheet.

A camera downloads video only while a Camera panel shows it. Until then it shows as ready and uses no bandwidth. Data never waits behind video: they travel in separate relay rooms.

Access and encryption

Whoever can watch the stream can watch its cameras. The relay sees only ciphertext. The camera has its own key. Outside projects it is derived from the same password or API key secret as the stream’s, with its own salt. In an end-to-end encrypted project it is a random key per epoch, sealed under the project key.

In an end-to-end encrypted project a Python camera needs no second approval: it is published by the same sender device as its stream.

Use a dedicated API key for cameras, ideally a project key, and only let a device remember it on a machine you control.

Bandwidth

Plan on about 2 Mbit/s for 720p and 4 Mbit/s for 1080p, uploaded from the camera machine, and only while the camera has viewers. Plans with cameras allow up to 6,000 kbit/s per camera.

Plan limits

The count is registered cameras. Over the limit, registering a new camera is refused with “Your plan includes {n} cameras.” If a plan drops to 0 cameras, its cameras lose their access and are refused with “Your plan includes 0 cameras.” A pilot on another plan can be arranged with us.

Low-quality copy

A camera can also publish a low-quality copy (a low layer) next to its full-quality video. It is 360p at 15 fps and about 400 kbit/s, and it is not recorded. The copy is not counted as a camera of your plan.

• Browser: the /camera page has “Low-quality copy for camera walls”, on by default.
• Python: stream.add_camera(..., low=True). On Linux and macOS one ffmpeg writes both outputs. On Windows a second ffmpeg opens the input again, which a dshow webcam does not allow, so low=True with input_format="dshow" raises an error. An IP camera works.
• A Camera panel narrower than 640 px plays the low copy and shows an “LQ” tag. It goes back to full quality at 720 px. A camera without a low copy plays at full quality at any size.
• Like the full video, the copy is sent only while someone watches it.

Camera wall

One Camera panel can show up to 9 cameras. In the panel’s settings, tick the cameras in the order you want them. Two cameras sit side by side, 3 or 4 make a 2x2 grid, and 5 to 9 make a 3x3 grid. Each tile is labelled with its stream and camera name.

Tiles use the low copy when a camera has one. Click a tile to show that camera alone, at full quality when the panel is wide. “All cameras” or Escape goes back to the wall. In live mode every tile follows the live picture. When the panel is synced to the cursor or a recording, all tiles show the same instant.

Recordings

When a stream is recorded in the cloud, its cameras are recorded with it. Only the full-quality video is recorded, not the low copy. A camera starts recording within about 10 seconds of its stream, because it follows the stream’s heartbeat.

• The camera recordings belong to the stream’s recording. They are moved to the trash, restored and expired together with it.
• The recordings list shows “N cameras” on a recording that has video.
• Opening a recording brings its cameras. A Camera panel on a worksheet that shows the recording plays the recorded video at the chart cursor, or at the end of the X range, or at the start of the recording. The overlay says “Recording” instead of live, with the Exact or Approx. badge.
• The video is downloaded in pieces as you seek, not all at once.
• CSV and MF4 exports do not include video.
• Camera video counts toward the recording storage of your plan.

Usage

Account shows “Video this month: N cameras · H viewer-hours · X recorded”. Organization owners and admins see it on the Billing tab. It covers the current month and is updated hourly. It is a measurement of what was used.