Callback Functions

Result Callback

The detection results are delivered asynchronously via a callback function.

Result Structure

typedef struct {
    float     time_sec;       // Window start time (seconds from capture start)
    uint64_t  timestamp_ms;   // Absolute timestamp (ms)
    float     cry_prob;       // Cry probability [0, 1]
    int       is_cry;         // Binary result (cry_prob >= 0.5 → 1)
} cry_detect_result_t;

Callback Type

typedef void (*cry_detect_callback_t)(
    const cry_detect_result_t *result,
    void *user_data
);

The callback is invoked every 1 second (the processing step interval). Inside the callback:

Do not block — — the processing thread waits for the callback to return

Do not call `cry_detect_stop()` or `cry_detect_deinit()` — from inside the callback (will deadlock)

• The `result` pointer is valid only during the callback invocation — copy the data if you need it later

Example

void my_callback(const cry_detect_result_t *result, void *user_data) {
    my_context_t *ctx = (my_context_t *)user_data;

    printf("[%.3f] cry_prob=%.4f is_cry=%d
",
           result->time_sec, result->cry_prob, result->is_cry);

    if (result->is_cry) {
        ctx->cry_event_count++;
        // Trigger external action (LED, buzzer, notification, etc.)
    }
}

// Register callback
cry_detect_config_t config = {
    .callback = my_callback,
    .callback_data = &my_context,
};

Alarm Callback

The alarm strategy converts per-frame probabilities into higher-level alarm events, reducing jitter and false triggers.

Alarm Event Structure

typedef struct {
    float start_time;       // Event start time (seconds)
    float end_time;         // Event end time (seconds)
    float confidence;       // Average probability over the event
    float max_confidence;   // Maximum probability within the event
    int   frame_count;      // Number of frames in the event
    int   is_onset;         // 1 = cry started, 0 = cry ended (or flush)
} alarm_event_t;

Alarm Callback Type

typedef void (*alarm_callback_t)(
    const alarm_event_t *event,
    void *user_data
);

Example

void my_alarm_callback(const alarm_event_t *event, void *user_data) {
    if (event->is_onset) {
        printf("Alarm STARTED at %.1fs (confidence: %.2f)
",
               event->start_time, event->confidence);
    } else {
        printf("Alarm ENDED at %.1fs (duration: %.1fs, max conf: %.2f)
",
               event->end_time,
               event->end_time - event->start_time,
               event->max_confidence);
    }
}

// Register alarm callback
cry_detect_config_t config = {
    .callback = my_callback,
    .alarm_strategy = "asymmetric_envelope",
    .alarm_params = "high_thr=0.85,low_thr=0.35,min_duration=1.0",
    .alarm_callback = my_alarm_callback,
};

Alarm Strategies

Asymmetric Envelope (Recommended)

The "asymmetric_envelope" strategy uses a fast-attack, slow-release approach:

Attack — (rising edge): quickly follows the probability upward

Release — (falling edge): slowly decays, preventing brief dips from ending the alarm

High threshold — triggers alarm onset (default 0.85)

Low threshold — triggers alarm end (default 0.35)

Configuration parameters (passed via alarm_params):

The alarm strategy can also be used standalone:

alarm_strategy_t *s = alarm_strategy_create("asymmetric_envelope", NULL);
alarm_event_t event;

for each frame:
    if (s->update(s, prob, timestamp, &event))
        on_alarm_event(&event);

s->flush(s, &event);   // end of stream
s->destroy(s);