Skip to main content

Recordings

There are two types of recordings in Viseron, event recordings and continuous recordings.

Event recordings​

Event recordings are triggered by events such as motion detection or object detection. The recordings are saved to disk and can be viewed in the web interface on the Events tab on the Events page.

The config option trigger_event_recording: true instructs Viseron to start recording when the event is detected.

Example configuration to record when detecting a person:

darknet: # or any other object detector component
  object_detector:
    cameras:
      camera_one:
        fps: 1
        scan_on_motion_only: false
        labels:
          - label: person
            confidence: 0.7
            trigger_event_recording: true
info

By default, event recordings are stored for 7 days. This can be changed by setting retention rules.

info

The trigger_event_recording option is only available for motion and object detectors.

Continuous recordings​

If configured, continuous recordings are always running and stored to disk. The recordings can be viewed in the web interface on the Timeline tab on the Events page.

To enable continuous recordings, all you need to do is set retention rules since the default value of continuous_recording is true.

info

There are several ways to set retention rules. See the retention rules section for more information.

Example configuration to record continuously:

ffmpeg: # or any other camera component
  camera:
    camera_one:
      name: Camera 1
      host: !secret camera_one_host
      path: /Streaming/Channels/101/
      username: !secret camera_one_username
      password: !secret camera_one_password
      recorder:
        continuous_recording: true  # Not needed since it is the default, included for clarity
        continuous:  # Example of setting a max size of 10 GB for this individual camera
          max_size:
            gb: 10

Retention rules​

There are a number of ways to control the retention of recordings.

tip

Storage tiers can be used to move recordings to different storage locations based on age or size.

See the storage component tiers documentation for more information.

Setting retention rules for all cameras​

To use the same retention rules for all cameras it is recommended to use the storage component.

warning

Size based retention rules are calculated per camera, meaning that if you have 2 cameras and set a max_size of 1 GB, each camera can store 1 GB of recordings for a total of 2 GB.

Example configuration to set retention rules for all cameras:

storage:
  recorder:
    tiers:
      - path: / # Video segments will be stored in the /segments directory
        events:
          max_age:
            days: 14
        continuous:
          max_size:
            gb: 10
tip

This will enable continuous recordings for all cameras. If you want to disable continuous recordings for a specific camera, you can set continuous_recording: false in the cameras recorder configuration.

Setting retention rules for a specific camera​

You can set retention rules for a specific camera by adding the events, continuous or storage key to the camera config.

Example configuration to set retention rules for a specific camera:

ffmpeg: # or any other camera component
  camera:
    camera_one:
      name: Camera 1
      host: !secret camera_one_host
      path: /Streaming/Channels/101/
      username: !secret camera_one_username
      password: !secret camera_one_password
      recorder: # Store only events for 14 days
        events:
          max_age:
            days: 14

File format​

The recordings are saved in short .m4s (aka fMP4 or fragmented MP4) segments.

In the web interface the recordings are played back using HLS and the hls.js library. When you request a recording in the web interface, the server API will generate an HLS playlist and serve the segments to the client.

warning

The recordings are not playable on their own since they are fragmented. If you want to play the recordings outside of the web interface you will need to download the recordings.

Alternatively you can point your media player to the HLS playlist URL (the same used by the web interface), but this is currently not documented.

Downloading recordings​

From the web interface you can download recordings to an .mp4 file.

Downloading an event recording​

To download an event recording, you use the Download Recording button in the event details popup on the Events tab. It will download the selected event to an .mp4 file.

Downloading a continuous recording​

By using the Download button on the Events or Timeline tab you can download a continuous recording. It will download the selected time range to an .mp4 file.

info

If you have multiple cameras selected, one file per camera will be downloaded.

Create MP4 files for all event recordings​

If you want to create .mp4 files for all event recordings you can use the create_event_clip configuration option.

ffmpeg: # or any other camera component
  camera:
    camera_one:
      name: Camera 1
      host: !secret camera_one_host
      path: /Streaming/Channels/101/
      username: !secret camera_one_username
      password: !secret camera_one_password
      recorder:
        create_event_clip: true
warning

This will create .mp4 files for all event recordings, which will be stored in addition to the .m4s files.

THe .mp4 files will be created in the /event_clips directory, unless you have set a different path in the storage component.