Recording API#

The recording API of Oasis supports two methods.

Combined Recording API: A method that saves multiple video channels into a single recording file
Individual Recording API: A method that saves each video channel into an individual recording file

Specifying the Recording File Path#

Normal recording starts by calling startRecording for combined recording or startMultiChannelRecording for individual recording.

The callback function MediaObserver::queryNewFilePath for combined recording or MediaObserver2::queryNewFilePaths for individual recording is called.

The automatically generated file path is delivered as an argument to the callback function.

In the case of combined recording, the format of the automatically generated file path consists of a combination of parameter key values, date, and time as follows:

<normal-folder-path>/<file-prefix>YYYY-MM-DD-hh-mm-ss.<file-extension>

In the case of individual recording for each video channel, it is as follows:

<normal-folder-path>/<file-prefix>YYYY-MM-DD-hh-mm-ss-CH<N>.<file-extension>

<N> is the channel number, such as 1, 2, 3, etc.

The application can change the recording file path delivered as a parameter of this function.

Event and motion recording deliver the recording file path directly as an API argument.

Each recording file path is an absolute path.

It is recommended to use the folder path value delivered when creating the recording object as the folder where the recording file is located, though specifying another folder is also possible.

normal-folder-path
event-folder-path
motion-folder-path

Parameter Configuration#

The combined recording method and individual recording method deliver a key-value map as a parameter when creating each recording object as follows.

file-prefix

oasis-

The prefix used when generating file names. If it is an empty string, no prefix is applied to the automatically generated file name. It can be overwritten in MediaObserver::queryNewFilePath.

file-extension

avi

The file extension. Enter either avi or mp4.

file-duration-secs

60

The total recording time, measured in seconds. When the total recording time elapses or the file size limit is reached, recording starts with a new file. The new file name can be verified and overwritten in MediaObserver::queryNewFilePath.

normal-folder-path

/mnt/extsd/NORMAL

The recording folder path used to automatically generate the absolute path of normal recording files. Fill in the normal recording folder set during the Oasis File System (OFFS) formatting. If a folder on a file system other than the location where OFFS is mounted is filled in, the default file size is limited to 16MB, but the default file size can be changed by calling oasis::fs::offsConfigLocalFormatInfo.

event-folder-path

/mnt/extsd/EVENT

The event recording folder path for media data cache storage. Fill in the event recording folder set during the Oasis File System (OFFS) formatting. Specifying a folder at a location where another readable and writable file system is mounted is also fine. It applies only when the enable-persistent-cache key value is "1". The actual event recording specifies the path in event recording APIs such as startEventRecording.

motion-folder-path

/mnt/extsd/MOTION

The motion recording folder path for media data cache storage. Fill in the motion recording folder set during the Oasis File System (OFFS) formatting. Specifying a folder at a location where another readable and writable file system is mounted is also fine. It applies only when the enable-persistent-cache key value is "1". The actual motion recording specifies the path in motion recording APIs such as startMotionRecording.

event-pre-recording-seconds

10

Specifies the recording time before an event occurs, measured in seconds. Minimum 0 seconds, maximum 60 seconds. It is determined by considering the memory cache size, disk writing, bitrate, etc.

event-post-recording-seconds

10

Specifies the recording time after an event occurs, measured in seconds. Minimum 0 seconds, maximum 60 seconds.

motion-pre-recording-seconds

10

Specifies the recording time before motion occurs, measured in seconds. Minimum 0 seconds, maximum 60 seconds.

motion-post-recording-seconds

10

Specifies the recording time after motion occurs, measured in seconds. Minimum 0 seconds, maximum 60 seconds.

disable-event-recording

0

Disables event recording.

disable-offs-recording

0

Does not write recording data to the file system.

max-files

5

The maximum number of recording files. If "0", it records without a limit on the number of recording files. When the recording folder capacity is full, the oldest file is deleted and recording restarts.

delete-oldest-file-on-max-files

1

If the value is "1", when the maximum number of recording files is reached, the oldest recording file is deleted, and recording restarts with a new file name. If the value is "0", when the maximum number of recording files is reached, recording stops. Valid when max-files is 1 or greater.

recording-size-limit-threshold-seconds

2

Specifies the margin time when checking the allowed size of a recording file, measured in seconds. If recording is possible for this amount of time, it judges that the recording capacity is full and restarts recording with a new file name.

report-media-info-ex

0

If "1", MediaObserver::onInfoEx is called. If "0", MediaObserver::onInfo is called.

avi-strd-size-max

1920

The maximum size of the metadata header during AVI recording, measured in bytes.

mp4-udta-size-max

1920

The maximum size of the metadata header during MP4 recording, measured in bytes.

enable-persistent-cache

0

Specifies whether to use the folder path of the event-folder-path key value in the case of event recording, or the folder path of the motion-folder-path key value in the case of motion recording, as a temporary media data cache. Disk lifespan may be shortened. It is useful for systems that have constraints making it difficult to temporarily store media data in memory with the media-cache-size key value specified during Oasis initialization. If "1", the folder where event recording and motion recording files are located must be identical to event-folder-path or motion-folder-path. If the folder location is different, data before the occurrence of the event or motion will not be saved.

recording-file-header-write-interval-secs

1

Specifies the update cycle of the recording file container header. If "0", the header is saved at the end.

enable-sound

1

If the value is "1", audio is also recorded along with the video.

snd-path

○

The audio device path. Mandatory to specify when performing audio recording.

snd-input-channels

1

The number of audio channels.

snd-input-sample-size

16

The audio sample size, measured in number of bits.

snd-input-sampling-duration-msec

40

The audio sample buffer size, measured in milliseconds.

snd-input-sampling-rate

8000

The audio sampling rate.

aencoder-type

raw

The audio encoder type. Specify one of raw, aac, mp3. raw saves PCM data without encoding it.

aencoder-bitrate

○

The audio encoder bitrate.

osd-font-size

21

The font size, measured in points. If the value is "0", OSD is not applied.

osd-font-face

Serif

The OSD text font family name.

osd-font-path

The OSD text font file path. If not specified, the default font file specified during initialization is used.

osd-text-color

255,255,255

The OSD text color. The color format is "r,g,b" or a "rrggbb" or "aarrggbb" hexadecimal value. For example, white is like "255,255,255" or "ffffff".

osd-use-text-color

1

If the value is "1", the OSD text color is used. If the value is "0", characters are not displayed.

osd-use-bg-color

0

If the value is "1", the OSD text background color is used.

osd-bg-color

0,0,0

The OSD text background color.

osd-use-outline-color

0

If the value is "1", the character outline color is used.

osd-outline-color

255,255,255

The character outline color.

osd-horz-align

center

Specifies the horizontal alignment of the OSD text. Specify one of left, center, right.

osd-vert-align

bottom

Specifies the vertical alignment of the OSD text. Specify one of top, center, bottom.

channel-count

○

The number of video channels. If "0", only audio channels are recorded.

The key-value map allocated for each video track (channel) is as follows. channel<N>- is prepended to the key name. <N> starts from 1 and increases by 1.

channel<N>-camera-id

The camera device ID specified in configCameras.

channel<N>-ise-id

The ISD device ID. Applies in the case of AllWinner chipsets.

channel<N>-resolution

720p

The video encoding resolution. Specify one value among 2160p, 1440p, 1080p, 720p, 480p, 360p.

channel<N>-out-width

1280

The width of the encoded video. The minimum width is 256. It must be specified together with out-height.

channel<N>-out-height

720

The height of the encoded video. The minimum height is 128. It must be specified together with out-width.

channel<N>-bitrate

3145728

The encoding video bitrate.

channel<N>-fps

30

The video input FPS.

channel<N>-file-framerate

The frame rate when playing the recording file.

channel<N>-vencoder-type

The encoding type. Specify one value between h264, h265.

channel<N>-venc-framerate

30

The encoding frame rate.

channel<N>-venc-keyframe-interval

30

The key frame interval during encoding.

channel<N>-media-wait-timeout-secs

0

The maximum waiting time for video input. If time elapses without video input, it triggers a kRecordingErrorMediaDataTimeout event depending on configuration. If the value is "0", it does not trigger the event.

channel<N>-media-wait-timeout-notify-oneshot

1

If the value is "1", it triggers the video data timeout error event only once. If "0", it triggers it every time.

Below is the table of bitrates (bps) applied per resolution when bitrate is not specified and only resolution is specified.

Resolution	Width	Height	Bitrate
2160p	3840	2160	16000000
1440p	2560	1440	16000000
1080p	1920	1080	8000000
720p	1280	720	4000000
480p	640	480	2000000
360p	640	360	1000000

Below is the bitrate (bps) table when bitrate is not specified, and only out-width and out-height are specified.

Minimum Height	Bitrate
1440	8000000
1080	6000000
720	4000000
480	2000000
Less than 480	1000000

Note

When resolution, out-width, and out-height coexist, out-width and out-height are applied.

OSD can be configured for each video channel.

When the video encoding format is H264, the following key-value map applies.

channel<N>-h264-profile

high

The profile. Specify one value among baseline, main, high.

channel<N>-h264-level

level51

The level. Specify one value among level1, level11, level12, level13, level2, level21, level22, level3, level31, level32, level4, level41, level42, level5, level51, level52.

channel<N>-h264-min-qp

1

The minimum QP (Quantization Parameter) value. A lower value results in a higher quality video. Range value is 0~51.

channel<N>-h264-max-qp

51

The maximum QP (Quantization Parameter) value.

channel<N>-h264-enable-fixqp

0

Specifies whether to allow Intra coding within P frames. Enabled if "1". Supported depending on the chipset.

channel<N>-h264-fix-iqp

30

The fixed key frame QP. It has a value of 0~51.

channel<N>-h264-fix-pqp

30

The fixed P frame QP. It has a value of 0~51.

When the video encoding format is H265, the following key-value map applies.

channel<N>-h265-profile

main

The profile. Specify one value among main, main10, still.

channel<N>-h265-level

level51

The level. Specify one value among level1, level2, level21, level3, level31, level41, level5, level51, level52, level6, level61, level62.

channel<N>-h265-rc-mode

vbr

The bitrate control mode. Supported depending on the chipset. Specify one value among vbr, cbr, abr, fixqp.

channel<N>-h265-min-qp

1

The minimum QP (Quantization Parameter) value. A lower value results in a higher quality video. Range value is 0~51. Applied to cbr, vbr, abr.

channel<N>-h265-max-qp

51

The maximum QP (Quantization Parameter) value. Applied to cbr, vbr, abr.

channel<N>-h265-max-bitrate

1000000

The maximum bitrate. Applied to vbr, abr.

channel<N>-h265-min-iqp

30

The minimum key frame QP value. Applied to abr.

channel<N>-h265-max-iqp

51

The maximum key frame QP value. Applied to abr.

channel<N>-h265-quality

7

The quality value. It is in the range of 1~31. Higher means higher quality. Applied to vbr, abr.

channel<N>-h265-ratio-change-op

7

The Ratio Change Op value. It is in the range of 50~100. Applied to vbr, abr.

channel<N>-h265-fix-iqp

30

The fixed I frame QP value. Applied to fixqp mode.

channel<N>-h265-fix-pqp

30

The fixed P frame QP value. Applied to fixqp mode.

channel<N>-h265-gop-mode

normal

Specifies the GOP (Group of Pictures) mode. Supported depending on the chipset. One value of dual, smart, normal.

channel<N>-h265-gop-smart-virtual-interval

30

The key frame interval applied during smart mode.

channel<N>-h265-fast-encoding

0

Enables fast encoding. Supported depending on the chipset. Enabled if "1".

channel<N>-h265-enable-pframe-intra

Specifies whether to allow Intra coding within P frames. Enabled if "1". Supported depending on the chipset.

Recording Scenario Example#

Below is a scenario applicable to a dashcam.

Format with Oasis File System (OFFS) using mkfs.offs into the following folder structure. The mode of each folder during formatting is "0".
- DRIVING
- PARKING
- DRIVE_EVENT
- PARK_EVENT
Mount OFFS to /mnt/sd.
When creating a combined or individual recording object, specify normal-folder-path as the folder path /mnt/sd/DRIVING. Call the createRecorder or createMultiChannelRecorder API.
Start combined or individual recording. Call the startRecording or startMultiChannelRecording API.
When an event occurs, generate an absolute file path within the /mnt/sd/DRIVE_EVENT folder and call event recording. Call the startEventRecording or startMultiChannelEventRecording API.
Stop recording to switch to parking mode. Call the stopRecording or stopMultiChannelRecording API.
Change normal-folder-path to the /mnt/sd/PARKING folder.
Change file-duration-secs and each video channel's channel<N>-file-framerate and channel<N>-venc-framerate among the recording parameters to the timelapse configuration values.
Apply the changed parameters. Call the changeRecorderParameters or changeMultiChannelRecorderParameters API.
Restart recording. Call the startRecording or startMultiChannelRecording API.
If an event occurs during timelapse recording, generate an absolute file path within the /mnt/sd/PARK_EVENT folder and call event recording. Call the startEventRecording or startMultiChannelEventRecording API.