SpecsCapture
SPECS NDK reference for SpecsCapture, which records camera video, optional AR and microphone audio into a finished MP4 file.
SpecsCapture is the high-level, one-shot capture API on SPECS. It records camera video (optionally with an AR overlay composited in) and microphone audio, and finalizes a complete MP4 (video, audio, and metadata) to a file descriptor you supply. Terminal success or failure is reported asynchronously through an event callback.
Where SpecsRecorder hands you a live encoded bitstream to mux yourself, SpecsCapture owns the whole pipeline and writes a finished, seekable MP4. A capture session is single-use: one recording attempt per session, not reusable. Create a new session for each recording.
Include and link
#include <SpecsCapture.h>
target_link_libraries(myapp specs_media) # same library as SpecsMedia / SpecsRecorder
Required permissions: CAMERA_RAW and MICROPHONE_RAW. SpecsCapture_prewarm() and SpecsCapture_start() are both annotated with SPECS_REQUIRES_PERMISSION(CAMERA_RAW, MICROPHONE_RAW). Both must appear in your library's .snap.permissions manifest or the request is refused with a permission error. SpecsCapture_create(), SpecsCapture_stop(), and SpecsCapture_destroy() carry no permission annotation. See Permission Annotations and Manifest Embedding.
SpecsCapture result codes
All SpecsCapture functions return SpecsMedia_Result_t from SpecsMedia.h (see result codes in SpecsMedia.h). Terminal recording status is delivered as a SpecsMedia_Result_t inside the event callback's SpecsCapture_EventInfo_t::status.
The SpecsCapture output file descriptor
You open and own the destination file descriptor and pass it in SpecsCapture_CreateParams_t::outputFd. It must be a readable, writable, and seekable regular file opened O_RDWR (the muxer seeks back to patch the MP4 header on finalize). The file descriptor is required. Close it yourself after the terminal COMPLETED or ERROR event arrives.
Opaque session handle
// Since: v1.3.0
typedef struct SpecsCapture_s SpecsCapture_t;
SpecsCapture_t is the opaque capture session handle. SpecsCapture_create returns it and SpecsCapture_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.
SpecsCapture session lifecycle
create() ──▶ [prewarm()] ──▶ start() ──▶ stop() ──▶ (COMPLETED/ERROR) ──▶ destroy()
create(): supply all parameters up front and register the event callback.prewarm()(optional): warms the pipeline so a subsequentstart()has low latency; theREADYevent signals pre-warm is complete.start(): begin recording; the first accepted sample firesRECORDING_STARTED.stop(): request finalization (or let the configureddurationNsauto-stop the recording).COMPLETED(MP4 finalized) orERROR(terminal failure) arrives on the callback.destroy(): release the session. On a non-terminal session,destroy()cancels outstanding work: a recording in progress is stopped and finalized, and a pre-warmed session is cancelled. It blocks until any in-flight event callback has returned; no events are delivered after it returns, and the session must not be used afterwards. It returns once the camera has been released (normally well under a second, at most a few seconds), so a new session can be started immediately. It is safe to calldestroy()from within the session's own event callback: called there, it returns without waiting, and the nextprewarm()orstart()waits instead.
Leaving the foreground
If the app leaves the foreground (it moves to the background, or is suspended or stopped) while the session is preparing, recording or finalizing, the session ends: recording stops and the MP4 is finalized on a best-effort basis. The session is never restarted. SPECSCAPTURE_EVENT_COMPLETED is delivered if the MP4 is finalized and that result reaches the app. The app is usually suspended first, in which case the session ends with SPECSCAPTURE_EVENT_ERROR and status SPECSMEDIA_ERROR_SHUTDOWN once the app runs again, and the contents of the output file are unspecified.
SpecsCapture modes
// Since: v1.3.0
typedef enum SpecsCapture_Mode_t {
SPECSCAPTURE_MODE_VIDEO_AND_AUDIO = 0, // camera video + microphone audio
SPECSCAPTURE_MODE_VIDEO_WITH_AR_AND_AUDIO = 1, // camera video with AR composited in + audio
SPECSCAPTURE_MODE_VIDEO_ONLY = 2, // camera video only (reserved, not yet implemented)
SPECSCAPTURE_MODE_VIDEO_WITH_AR_ONLY = 3, // camera video with AR, no audio (reserved, not yet implemented)
} SpecsCapture_Mode_t;
Each mode records camera video into a single video track, optionally with AR composited in, and optionally with microphone audio. The _ONLY (no-audio) modes are reserved and not yet implemented: SpecsCapture_create() returns SPECSMEDIA_ERROR_NOT_IMPLEMENTED for them. Use SPECSCAPTURE_MODE_VIDEO_AND_AUDIO or SPECSCAPTURE_MODE_VIDEO_WITH_AR_AND_AUDIO. Additional layouts (for example separate camera and AR video tracks) may be added as new enumerators in a future release.
SpecsCapture AR blend modes
SpecsCapture_ArBlend_t applies only to the AR modes (SPECSCAPTURE_MODE_VIDEO_WITH_AR_AND_AUDIO or SPECSCAPTURE_MODE_VIDEO_WITH_AR_ONLY).
// Since: v1.3.0
typedef enum SpecsCapture_ArBlend_t {
SPECSCAPTURE_AR_BLEND_OPAQUE = 0, // blend using the overlay's rendered alpha
SPECSCAPTURE_AR_BLEND_ADDITIVE = 1, // add overlay without using its alpha
} SpecsCapture_ArBlend_t;
SpecsCapture events
// Since: v1.3.0
typedef enum SpecsCapture_Event_t {
SPECSCAPTURE_EVENT_READY = 0, // pre-warm complete; low-latency start ready
SPECSCAPTURE_EVENT_RECORDING_STARTED = 1, // first sample of this recording accepted
SPECSCAPTURE_EVENT_COMPLETED = 2, // MP4 and metadata finalized on the fd (terminal)
SPECSCAPTURE_EVENT_ERROR = 3, // terminal failure; see EventInfo::status
} SpecsCapture_Event_t;
COMPLETED and ERROR are terminal. (A future SPECSCAPTURE_EVENT_FRAME may be appended without breaking ABI.)
Video codec, audio codec, rate control, and resolution are not redefined in SpecsCapture.h. SpecsCapture reuses the shared SpecsMedia_VideoCodec_t, SpecsMedia_AudioCodec_t, SpecsMedia_RateControl_t, and SpecsMedia_Resolution_t from SpecsMedia.h.
SpecsCapture structures
// Since: v1.3.0
typedef struct SpecsCapture_CreateParams_s {
SpecsCapture_Mode_t mode; // what is recorded
SpecsMedia_Resolution_t resolution; // recording resolution
uint32_t bitrate; // target video bitrate; 0 = auto
uint32_t fps; // frame rate — currently ignored; capture runs at 30
SpecsMedia_RateControl_t rateControl; // encoder rate control mode
uint64_t durationNs; // recording duration in ns from when recording begins;
// 0 = record until SpecsCapture_stop()
int outputFd; // readable/writable/seekable O_RDWR fd for the MP4 (required, caller-owned)
SpecsMedia_VideoCodec_t videoCodec; // video codec; DEFAULT = H.265
SpecsMedia_AudioCodec_t audioCodec; // audio codec; DEFAULT = AAC
SpecsCapture_ArBlend_t arBlendMode; // AR blend mode (AR modes only)
double arAlpha; // alpha for OPAQUE blending, [0.0, 1.0] (AR modes only)
} SpecsCapture_CreateParams_t;
For integer fields of SpecsCapture_CreateParams_t, 0 selects the implementation default and the maximum value (for example UINT32_MAX) selects the highest supported value. The implementation may adjust any value to respect hardware limits.
// Since: v1.3.0
typedef struct SpecsCapture_EventInfo_s {
SpecsMedia_Result_t status; // SPECSMEDIA_SUCCESS, or an error on EVENT_ERROR
uint64_t recordedDurationNs; // on COMPLETED, recorded length in ns; 0 if unknown
const char *message; // optional detail; may be NULL; valid only during the callback
} SpecsCapture_EventInfo_t;
SpecsCapture event callback
// Since: v1.3.0
typedef void (*SpecsCapture_EventCallback_t)(SpecsCapture_t *session,
SpecsCapture_Event_t event,
const SpecsCapture_EventInfo_t *info,
void *cbk_context);
The SpecsCapture_EventCallback_t callback may be invoked on an internal thread and holds an internal delivery lock while it runs, so don't block in it. The info pointer (and its message) is valid only for the duration of the call.
SpecsCapture function reference
// Create a single-use capture session. All parameters are supplied up front.
// Returns SPECSMEDIA_ERROR_BAD_ARGUMENT if session or params is NULL or
// params->outputFd is negative; SPECSMEDIA_ERROR_NOT_IMPLEMENTED for
// SPECSCAPTURE_MODE_VIDEO_ONLY and SPECSCAPTURE_MODE_VIDEO_WITH_AR_ONLY.
// Since: v1.3.0
SpecsMedia_Result_t SpecsCapture_create(SpecsCapture_t **session,
const SpecsCapture_CreateParams_t *params,
SpecsCapture_EventCallback_t callbackFunction,
void *cbk_context);
// Optional: warm the pipeline for a low-latency start. Fires EVENT_READY.
// Requires CAMERA_RAW, MICROPHONE_RAW.
// Since: v1.3.0
SpecsMedia_Result_t SpecsCapture_prewarm(SpecsCapture_t *session);
// Begin recording. First accepted sample fires EVENT_RECORDING_STARTED.
// Requires CAMERA_RAW, MICROPHONE_RAW.
// Since: v1.3.0
SpecsMedia_Result_t SpecsCapture_start(SpecsCapture_t *session);
// Request finalization. On success EVENT_COMPLETED fires once the MP4 is written.
// If recording has not yet begun, this cancels the session. Returns
// SPECSMEDIA_ERROR_INVALID_STATE if called before prewarm() or start().
// Since: v1.3.0
SpecsMedia_Result_t SpecsCapture_stop(SpecsCapture_t *session);
// Release the session. Stops and finalizes a recording in progress, cancels a
// pre-warmed session, and waits for in-flight callbacks and for the camera to be
// released. Safe to call from the session's own callback, where it returns
// without waiting (the next prewarm() or start() waits instead).
// Since: v1.3.0
SpecsMedia_Result_t SpecsCapture_destroy(SpecsCapture_t *session);