SpecsRecorder
SPECS NDK reference for SpecsRecorder, which delivers encoded camera video, AR video or microphone audio frames through callbacks.
SpecsRecorder provides encoded stream recording on SPECS. It receives encoded natural (camera) video, AR (rendered overlay) video, or microphone audio frames from the platform recording pipeline through asynchronous callbacks. Use SpecsRecorder when you need an encoded bitstream directly (for example for recording, streaming, or network transmission) without managing the codec pipeline yourself.
Each session is single-stream: the SpecsRecorder_CreateParams_t passed to SpecsRecorder_create fixes the session's stream type (natural video, AR video, or audio), its codec, and, for AR video, the rendered eye view. Create separate sessions for separate streams.
Include and link
#include <SpecsRecorder.h>
// Transitively includes:
// SpecsMedia.h — error codes, result types, shared codec/encoding types
target_link_libraries(myapp specs_media)
Required permission: CAMERA_RAW. SpecsRecorder_streamStart is annotated with SPECS_REQUIRES_PERMISSION(CAMERA_RAW). The permission is recorded in your library's .snap.permissions manifest at build time; see Permission Annotations and Manifest Embedding.
Opaque session handle
// Since: v1.3.0
typedef struct SpecsRecorder_s SpecsRecorder_t;
SpecsRecorder_t is the opaque encoded stream handle. SpecsRecorder_create returns it and SpecsRecorder_destroy releases it. Use only pointers in API calls; don't rely on the layout or contents of the struct body, which is implementation-defined.
SpecsRecorder session lifecycle
SpecsRecorder_create() ← allocate session from CreateParams, register callback
│
├─ SpecsRecorder_configSet() ← optional: configure frame rate, bitrate, etc.
│
├─ SpecsRecorder_setResolution() ← optional: request a picture resolution (video, AR video)
│
├─ SpecsRecorder_getVideoResolution() ← optional: read the resolution the stream encodes
│
├─ SpecsRecorder_streamStart()
│
[STREAMING — callbacks deliver encoded frames]
│
├─ SpecsRecorder_action() ← optional: request key frame, change bitrate
│
├─ SpecsRecorder_streamStop()
│
└─ SpecsRecorder_destroy()
Threading model: the calls in the lifecycle run on the application thread and are used sequentially. Encoded frames arrive on a separate thread through the callback registered by SpecsRecorder_create; the callback is invoked only while the stream is active, after SpecsRecorder_streamStart succeeds and before SpecsRecorder_streamStop. The callback must not call SpecsRecorder_streamStop or SpecsRecorder_destroy; signal the application thread to stop instead.
SpecsRecorder stream types
// Since: v1.3.0
typedef enum SpecsRecorder_StreamType_t {
SPECSRECORDER_STREAM_TYPE_VIDEO = 0, // encoded natural (camera) video
SPECSRECORDER_STREAM_TYPE_AR_VIDEO = 1, // encoded AR (rendered overlay) video
SPECSRECORDER_STREAM_TYPE_AUDIO = 2, // encoded microphone audio
} SpecsRecorder_StreamType_t;
AR camera position
SpecsRecorder_ArCameraPosition_t selects which rendered view an AR video session produces. It applies only to SPECSRECORDER_STREAM_TYPE_AR_VIDEO and is fixed for the life of the session.
// Since: v1.3.0
typedef enum SpecsRecorder_ArCameraPosition_t {
SPECSRECORDER_AR_CAMERA_POSITION_UNSET = 0, // unspecified → right eye
SPECSRECORDER_AR_CAMERA_POSITION_LEFT_EYE = 1, // the frames shown on the left display
SPECSRECORDER_AR_CAMERA_POSITION_RIGHT_EYE = 2, // the frames shown on the right display
SPECSRECORDER_AR_CAMERA_POSITION_LEFT_RIGHT_EYES = 3, // the frames shown on both displays,
// side by side (left, then right)
SPECSRECORDER_AR_CAMERA_POSITION_CAPTURE_CAMERA = 4, // the AR rendered from the right color
// (capture) camera, framed to the default
// landscape 4:3 camera capture
} SpecsRecorder_ArCameraPosition_t;
Natively, the eye views are the display frames at the display's resolution, as sent to the display (pre-corrected for the display optics); LEFT_RIGHT_EYES places the two side by side. The CAPTURE_CAMERA view has the camera capture's 4:3 aspect with square pixels.
SpecsRecorder_create returns SPECSMEDIA_ERROR_NOT_IMPLEMENTED for stream types or AR camera positions that are not yet supported.
Create parameters
// Since: v1.3.0
typedef struct SpecsRecorder_CreateParams_s {
SpecsRecorder_StreamType_t streamType; // natural video, AR video, or audio
SpecsMedia_VideoCodec_t videoCodec; // used for VIDEO and AR_VIDEO
SpecsMedia_AudioCodec_t audioCodec; // used for AUDIO
SpecsRecorder_ArCameraPosition_t arCameraPosition; // used for AR_VIDEO only
} SpecsRecorder_CreateParams_t;
The unused codec field (and arCameraPosition for non-AR sessions) is ignored. Codecs are the shared SpecsMedia_VideoCodec_t and SpecsMedia_AudioCodec_t enums from SpecsMedia.h:
// Since: v1.3.0
typedef enum SpecsMedia_VideoCodec {
SPECSMEDIA_VIDEO_CODEC_DEFAULT = 0, // implementation default (H.265)
SPECSMEDIA_VIDEO_CODEC_H265 = 1, // ITU-T H.265 / HEVC
SPECSMEDIA_VIDEO_CODEC_H264 = 2, // ITU-T H.264 / AVC
} SpecsMedia_VideoCodec_t;
// Since: v1.3.0
typedef enum SpecsMedia_AudioCodec {
SPECSMEDIA_AUDIO_CODEC_DEFAULT = 0, // implementation default (AAC)
SPECSMEDIA_AUDIO_CODEC_AAC = 1, // AAC
} SpecsMedia_AudioCodec_t;
SpecsRecorder_create is a macro. In the header, SpecsRecorder_create(stream, params, cb, ctx) is a function-like macro that expands to the exported symbol SpecsRecorder_createWithParams(...). Call it exactly as documented in SpecsRecorder function reference (works in C and C++). If you resolve the entry point dynamically (for example with dlsym), look up SpecsRecorder_createWithParams.
SpecsRecorder frame structure
// Since: v1.3.0
typedef struct {
uint64_t timestamp_ns; // frame timestamp in nanoseconds
uint8_t *buffer; // encoded frame data
size_t buffer_size; // total bytes in buffer
} SpecsRecorder_Frame_t;
SpecsRecorder frame callback
// Since: v1.3.0
typedef void (*SpecsRecorder_FrameCallback_t)(const SpecsRecorder_Frame_t *frame,
void *cbk_context);
The SpecsRecorder_FrameCallback_t callback fires on an internal thread while the stream is active. The frame pointer and its buffer are valid only during the callback; copy the data if you need to retain it.
SpecsRecorder configuration
A field of SpecsRecorder_Config_t set to 0 requests that field's default (as is the case right after SpecsRecorder_create()); see each field for its default and valid range. Values outside a field's documented range are caller error. The implementation may adjust accepted values to hardware limits; read the applied configuration back with SpecsRecorder_configGet().
Rate control
Rate control is the shared SpecsMedia_RateControl_t enum from SpecsMedia.h. For SpecsRecorder video and AR sessions, 0 selects the default, SPECSMEDIA_RATE_CONTROL_DISABLE (constant QP); a value outside the enum makes configSet() fail with SPECSMEDIA_ERROR_BAD_ARGUMENT.
// Since: v1.3.0
typedef enum SpecsMedia_RateControl {
SPECSMEDIA_RATE_CONTROL_DISABLE = 0, // Constant QP (no rate control) — Recorder default
SPECSMEDIA_RATE_CONTROL_CBR = 1, // Constant Bitrate
SPECSMEDIA_RATE_CONTROL_CBR_VFR = 2, // Constant Bitrate, Variable Framerate
SPECSMEDIA_RATE_CONTROL_VBR_CFR = 3, // Variable Bitrate, Constant Framerate
SPECSMEDIA_RATE_CONTROL_VBR_VFR = 4, // Variable Bitrate, Variable Framerate
} SpecsMedia_RateControl_t;
Natural video parameters
SpecsRecorder_Video_Params_t is used for SPECSRECORDER_STREAM_TYPE_VIDEO. Resolution is the shared SpecsMedia_Resolution_t from SpecsMedia.h:
// Since: v1.3.0
typedef struct {
SpecsMedia_Resolution_t resolution; // requested picture resolution, a suggestion (see
// SpecsRecorder_setResolution); read back with
// configGet() or getVideoResolution()
uint32_t fps; // requested frame rate; resolved to the nearest of 30, 15, 10,
// 6, 5, 3, 2, 1 (every Nth frame of the ~30 fps camera);
// 0 = default (30) — read back with configGet()
uint32_t keyFrameInterval; // interval between IDR frames in frames;
// 0 = default; valid range 1-300
uint32_t bitrate; // bps; 0 = default; ignored when rateControl is DISABLE
SpecsMedia_RateControl_t rateControl; // 0 = default (DISABLE: constant QP)
} SpecsRecorder_Video_Params_t;
AR video parameters
SpecsRecorder_AR_Params_t is used for SPECSRECORDER_STREAM_TYPE_AR_VIDEO. It has no resolution field: request one with SpecsRecorder_setResolution and read the result with SpecsRecorder_getVideoResolution. For the native size of each AR view, see AR camera position.
// Since: v1.3.0
typedef struct {
uint32_t fps; // output frame rate; resolved to the nearest of 30, 15, 10,
// 6, 5, 3, 2, 1 (every Nth frame of the ~30 fps compositor);
// 0 = default (30). The stream keeps this rate while the lens
// is not rendering — read back with configGet()
uint32_t keyFrameInterval; // interval between IDR frames in frames;
// 0 = default; valid range 1-300
uint32_t bitrate; // bps; 0 = default; ignored when rateControl is DISABLE
SpecsMedia_RateControl_t rateControl; // 0 = default (DISABLE: constant QP)
} SpecsRecorder_AR_Params_t;
Audio parameters
SpecsRecorder_Audio_Params_t is used for SPECSRECORDER_STREAM_TYPE_AUDIO.
// Since: v1.3.0
typedef struct {
uint32_t sampleRate; // input sample rate in Hz
uint32_t channelCount; // number of audio channels
uint32_t bitsPerSample; // bits per sample
uint32_t bitrate; // target encoded bitrate
} SpecsRecorder_Audio_Params_t;
Config structure
// Since: v1.3.0
typedef struct {
SpecsRecorder_Video_Params_t video; // natural (camera) video — STREAM_TYPE_VIDEO
SpecsRecorder_Audio_Params_t audio; // audio — STREAM_TYPE_AUDIO
SpecsRecorder_AR_Params_t ar; // AR video — STREAM_TYPE_AR_VIDEO
} SpecsRecorder_Config_t;
Only one member is meaningful at a time; the streamType in the SpecsRecorder_CreateParams_t passed to SpecsRecorder_create() determines which one applies. You can set the configuration only after the session is created and before it is started.
SpecsRecorder video resolution
The picture resolution of a video session (SPECSRECORDER_STREAM_TYPE_VIDEO or SPECSRECORDER_STREAM_TYPE_AR_VIDEO) is a request, set with SpecsRecorder_setResolution. It is a suggestion: the stream encodes a supported resolution chosen from it, which may differ, so query the resolution the stream will actually produce with SpecsRecorder_getVideoResolution. {0, 0} requests the source's native resolution. A resolution that differs from the native one shows the center of the source, cropped rather than stretched.
For SPECSRECORDER_STREAM_TYPE_VIDEO, SpecsRecorder_setResolution is the same setting as SpecsRecorder_Config_t::video.resolution. For SPECSRECORDER_STREAM_TYPE_AR_VIDEO, it is the only resolution setting.
SpecsRecorder_VideoResolution_t
Since: v1.3.0
The picture sizes of a video session, filled in by SpecsRecorder_getVideoResolution.
// Since: v1.3.0
typedef struct SpecsRecorder_VideoResolution_s {
SpecsMedia_Resolution_t encoded; ///< Size of the encoded pictures.
SpecsMedia_Resolution_t native; ///< The source's native resolution ({0, 0} request).
} SpecsRecorder_VideoResolution_t;
| Field | Description |
|---|---|
encoded | Size of the encoded pictures. |
native | The source's native resolution (what a {0, 0} request produces). |
SpecsRecorder session info
You can query the immutable session properties chosen at create() time with SpecsRecorder_getSessionInfo:
// Since: v1.3.0
typedef struct SpecsRecorder_SessionInfo_s {
SpecsRecorder_CreateParams_t params; // create parameters for this session
SpecsRecorder_FrameCallback_t callbackFunction; // installed frame callback
void *cbk_context; // opaque user context
} SpecsRecorder_SessionInfo_t;
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_getSessionInfo(SpecsRecorder_t *stream,
SpecsRecorder_SessionInfo_t *info);
SpecsRecorder runtime actions
// Since: v1.3.0
typedef enum SpecsRecorder_Action_t {
SPECSRECORDER_ACTION_REQUEST_KEY_FRAME = 0, // force a keyframe
SPECSRECORDER_ACTION_TARGET_BITRATE = 1, // change bitrate (value = bits/s)
SPECSRECORDER_ACTION_TARGET_FPS = 2 // change frame rate (value = fps) — not yet implemented
} SpecsRecorder_Action_t;
SpecsRecorder function reference
// Create an encoded stream session. params (must not be NULL) fixes the stream
// type, codec, and AR view for the life of the session; the callback is
// registered at creation time. Returns SPECSMEDIA_ERROR_NOT_IMPLEMENTED for
// stream types or AR camera positions that are not yet supported.
// (Implemented as a macro over the exported SpecsRecorder_createWithParams.)
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_create(SpecsRecorder_t **stream,
const SpecsRecorder_CreateParams_t *params,
SpecsRecorder_FrameCallback_t callbackFunction,
void *cbk_context);
// Destroy the session and free resources. Must not be called from the frame
// callback: from there it returns SPECSMEDIA_ERROR_INVALID_STATE and the
// stream is left intact.
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_destroy(SpecsRecorder_t *stream);
// Get current configuration.
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_configGet(SpecsRecorder_t *stream,
SpecsRecorder_Config_t *config);
// Set configuration (call before streamStart). Some values may be clamped or
// rounded by the implementation to respect hardware limits; call configGet()
// afterwards to read back the actual values applied. Returns
// SPECSMEDIA_ERROR_BAD_ARGUMENT for an invalid enumeration value.
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_configSet(SpecsRecorder_t *stream,
const SpecsRecorder_Config_t *config);
// Request the picture resolution of a video session (a suggestion; see
// SpecsRecorder video resolution). {0, 0} requests the source's native
// resolution. Valid while the stream is not running, like configSet().
// resolution must not be NULL. Returns SPECSMEDIA_ERROR_BAD_ARGUMENT for a NULL
// argument or an audio session, SPECSMEDIA_ERROR_INVALID_STATE while the
// stream is running.
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_setResolution(
SpecsRecorder_t *stream, const SpecsMedia_Resolution_t *resolution);
// Get the resolution a video session encodes for the current request and the
// native resolution of its source. Valid before and after streamStart(). For
// an AR session that is not running, this asks the media service, which takes
// a moment. resolution must not be NULL. Returns SPECSMEDIA_ERROR_BAD_ARGUMENT
// for a NULL argument or an audio session, SPECSMEDIA_ERROR_GENERIC if the
// media service cannot be reached.
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_getVideoResolution(
SpecsRecorder_t *stream, SpecsRecorder_VideoResolution_t *resolution);
// Query immutable session properties chosen at create() time.
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_getSessionInfo(SpecsRecorder_t *stream,
SpecsRecorder_SessionInfo_t *info);
// Start / stop frame delivery (encoder running). streamStop must not be called
// from the frame callback: from there it returns SPECSMEDIA_ERROR_INVALID_STATE
// and the stream keeps running.
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_streamStart(SpecsRecorder_t *stream);
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_streamStop(SpecsRecorder_t *stream);
// Perform a runtime action while streaming.
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_action(SpecsRecorder_t *stream,
SpecsRecorder_Action_t action,
uint64_t value);
The SpecsRecorder_create macro and its exported symbol
SpecsRecorder_create is how you normally create a session. In SpecsRecorder.h it is a function-like macro that forwards its four arguments to the exported function SpecsRecorder_createWithParams, which has the same parameters and return type:
// Exported symbol behind SpecsRecorder_create. Look this name up when you
// resolve the entry point dynamically (for example, with dlsym).
// Since: v1.3.0
SpecsMedia_Result_t SpecsRecorder_createWithParams(SpecsRecorder_t **stream,
const SpecsRecorder_CreateParams_t *params,
SpecsRecorder_FrameCallback_t callbackFunction,
void *cbk_context);
// Since: v1.3.0
#define SpecsRecorder_create(stream, params, callbackFunction, cbk_context) \
SpecsRecorder_createWithParams((stream), (params), (callbackFunction), (cbk_context))
Call SpecsRecorder_create(&rec, ¶ms, on_frame, my_ctx) in your code; the macro works in C and C++.
Example: AR video session
SpecsRecorder_CreateParams_t params = {
.streamType = SPECSRECORDER_STREAM_TYPE_AR_VIDEO,
.videoCodec = SPECSMEDIA_VIDEO_CODEC_H264,
.arCameraPosition = SPECSRECORDER_AR_CAMERA_POSITION_RIGHT_EYE,
};
SpecsRecorder_t *rec = NULL;
if (SpecsRecorder_create(&rec, ¶ms, on_frame, my_ctx) != SPECSMEDIA_SUCCESS) {
/* handle error */
}
SpecsRecorder_Config_t cfg = {0};
cfg.ar.bitrate = 8000000;
cfg.ar.rateControl = SPECSMEDIA_RATE_CONTROL_CBR;
SpecsRecorder_configSet(rec, &cfg);
SpecsMedia_Resolution_t want = {0, 0}; // the view's native resolution
SpecsRecorder_setResolution(rec, &want);
SpecsRecorder_VideoResolution_t res;
if (SpecsRecorder_getVideoResolution(rec, &res) == SPECSMEDIA_SUCCESS) {
/* res.encoded is the size of the pictures the stream will deliver */
}
SpecsRecorder_streamStart(rec);
/* ... */
SpecsRecorder_streamStop(rec);
SpecsRecorder_destroy(rec);