Is the Nx Cloud up? Visit our Status Page for the current health and performance of the Nx Cloud.

Status Page

Export video using the REST API

Nx Support
Updated

Nx Witness allows you to export video archives from a camera using the HTTP GET method. In the API Documentation, refer to the Video API section and find Device HTTP Stream (or Device HTTP Stream (format)) which you can use to download video archives from a camera.

Note: The archive for your specified timestamps must exist on the server before you can retrieve it. If the archive does not exist, the download fails.

Export a camera archive

To download a video archive segment, you must provide the camera ID, the start time position, and the duration. Supported download formats include: webm, mpegts, mpjpeg (multipart JPEG), mp4, mkv, 3gp, rtp, flv, and f4v.

Note: You can usually export mkv and mp4 videos without transcoding. Nx Witness forces transcoding if you apply any of the following settings:

  • Resolution or aspect ratio changes
  • Rotation or zoom (cropping)
  • Dewarping or image enhancement
  • A differing video codec
  • Setting the accurateSeek parameter to true
  • Adding a visible watermark

Request URL format

GET http://<server_ip>:<port>/rest/v4/devices/{id}/media.mkv?positionMs=<ms_since_epoch>&durationMs=<milliseconds>

Refer to this article to learn how to find your camera id.

Example request

GET http://127.0.0.1:7001/rest/v4/devices/5bafc0e9-56be-97f8-5034-45a50cecf3d8/media.mkv?positionMs=1499904000000&durationMs=100000

Query parameters

You can append the following query parameters to your request:

  • stream (string/integer): The stream quality. By default, the server determines this automatically based on the destination resolution. Append &stream=0 or &stream=primary for high quality. Append &stream=1 or &stream=secondary for low quality.
  • positionMs (integer): The start time specified in milliseconds since epoch. If omitted, the server provides a live stream instead of an archive.
  • endPositionMs (integer): The archive stream end position in milliseconds since epoch. Use this only when positionMs is present as an alternative to durationMs.
  • durationMs (integer): The fragment length in milliseconds. Works for both live and archive streams. For archive streams, this functions as an alternative way to specify endPositionMs.
  • quality (string): The video quality level used when transcoding a stream. Allowed values are lowest, low, normal, high, highest, and present.
  • format (string): The output container or stream format. You normally set this via the URL file extension (such as media.mkv or media.mp4). Allowed values are webm, mpegts, mpjpeg, mp4, mkv, 3gp, rtp, flv, and f4v. Default is mkv.
  • accurateSeek (boolean): Set to true to seek to the exact timestamp provided by positionMs. When set to false, it seeks to the nearest keyframe to the left of positionMs on the timeline. Enabling this forces transcoding. Default is false.
  • aspectRatio (string): The output aspect ratio (for example, 4:3 or 16:9). Use auto to use the aspect ratio set in the Device Settings dialog.
  • audioOnly (boolean): Set to true to send only the audio stream and omit the video. This requires audio permissions on the device. For live streams, audio must be enabled on the camera; for archives, the recording must contain an audio track.
  • dewarping (boolean): A transcoding option that enables fisheye image dewarping. If omitted, dewarping follows the value set in the Device Settings dialog. When set to true, the following sub-parameters apply:
  • dewarpingFov (number): Field of view, in radians.
  • dewarpingPanofactor (integer): Aspect-ratio correction multiplier. Allowed values are 1, 2, or 4.
  • dewarpingXangle (number): Pan angle, in radians.
  • dewarpingYangle (number): Tilt angle, in radians.
  • dropLateFrames (integer): Enables dropping late frames to keep the stream near real-time. The value specifies the maximum number of frames to buffer before the server drops the oldest ones. Defaults to 1 when enabled. If omitted, the server does not drop late frames.
  • realTimeOptimization (boolean): Set to true to turn on real-time transcoding optimization. This drops frames if the CPU lacks the capacity to transcode in real time.
  • resolution (string): The exact output resolution for the video. The format is {width}x{height} (such as 320x240) or height-only (such as 240p). This takes precedence over resolutionWhenTranscoding if you provide both. Defaults to the primary stream's native resolution when transcoding is off. When transcoding is on, defaults to the lesser of 1080p and the high stream's native resolution.
  • resolutionWhenTranscoding (string): The resolution to use only if the video is transcoded due to a codec mismatch or other transcoding option. Overridden by resolution if both are set.
  • rotation (string): The video rotation setting. Allowed values are auto, 0, 90, 180, and 270.
  • signature (boolean): Set to true to add a cryptographic signature to the exported media data for anti-tampering verification. Supported only for mp4 and webm formats.
  • standFrameDuration (boolean): Set to true to limit the stream speed to real-time. Frames are paced by their actual duration instead of being transmitted as fast as possible.
  • utcTimestamps (boolean): Set to true to use absolute UTC timestamps in the exported media data. Supported only for the mp4 format.
  • videoCodec (string): Forces a specific output video codec (such as h264 or h265). Returns an error if the codec is missing or unsupported by the selected container format.
  • zoom (string): Zooms into or crops a selected image region. The format is {x},{y},{width}x{height} where all values must be within the range [0..1].

Retrieve a list of archive chunks

To discover existing archive pieces (chunks) for a specific camera based on a time interval, use the footage endpoint.

Request URL format

GET http://<server_ip>:<port>/rest/v4/devices/{id}/footage

Example request

GET http://127.0.0.1:7001/rest/v4/devices/5bafc0e9-56be-97f8-5034-45a50cecf3d8/footage

Query parameters

You can filter and format the footage response using the following query parameters:

  • startTimeMs (integer): The start time of the search interval in milliseconds since epoch.
  • endTimeMs (integer): The end time of the search interval in milliseconds since epoch.
  • analyticsEngineId (string): Filters chunks by a specific analytics engine ID.
  • audioOnly (boolean): Set to true to filter for segments that contain audio.
  • detailLevelMs (integer): The chunk detail level in milliseconds. The server discards time periods shorter than this value.
  • format (string): The response body serialization format. Allowed values are JSON, XML, and CSV. Default is JSON.
  • keepSmallChunks (boolean): Set to true to retain standalone chunks that are smaller than the specified detailLevelMs.
  • maxCount (integer): The maximum number of chunks to return in the response.
  • periodType (string): The type of chunk to discover. Allowed values are recording, motion, and analytics.
  • preciseBounds (boolean): Set to true to precisely crop the returned chunks to the specified startTimeMs and endTimeMs boundaries.
  • quality (string): The recorded stream quality to include. Allowed values are both, low, and high. Default is both.
  • storageLocation (string): The storage target to search for footage. Allowed values are main, backup, and both. Default is both.

Motion-specific parameters

Use the following parameter only when you set periodType to motion:

  • motion (string): The bounding box coordinates to filter for motion, formatted as {x},{y},{width}x{height}. All coordinate values must be within the range [0..1].

Analytics-specific parameters

Use the following parameters only when you set periodType to analytics:

  • objectTrackId (string): Filters by a specific object track identifier.
  • objectTypeId (string): Filters by a specific analytics object type identifier.
  • analyticsEngineId (string): Filters by a specific analytics engine identifier.
  • boundingBox (string): The coordinates of the target area formatted as {x},{y},{width}x{height}. All values must be within the range [0..1].
  • freeText (string): A space-separated or comma-separated set of keywords. The server performs a wildcard search across all available object attribute values.
  • maxAnalyticsDetailsMs (integer): The analytic details limit expressed in milliseconds.
  • needFullTrack (boolean): Set to true to include full track details (geometry data) in the response.
  • options (string): Specific analytics filter exclusions. Allowed values are none, ignoreTextFilter, ignoreBoundingBox, and ignoreTimePeriod.
  • storageId (string): Filters chunks by a specific storage target ID.

Related articles

Comments

0 comments

Article is closed for comments.