枪声检测：嵌入式离线枪声识别 SDK 与公共安全部署新增
枪声检测的价值（场景、流程）
在公共安全场景，事件发生到响应之间的每一秒都关键。枪声有独特的声学指纹——与摄像头不同，麦克风在黑暗中、拐角处、开阔空间都能工作。从一所校园到一座城市，声学感知在人眼稀疏的地方加上持续的觉察层。
枪声的特点（时域与频域）
下图为一条真实枪声音频（含多次射击）——上为波形图、下为梅尔频谱图，毫秒级突起的尖峰与宽频垂直条纹清晰可见：
试听素材（真实样本，点击播放）：
🔊 真实枪声样本
🔊 另一段枪声样本
毫秒级上升沿 — ——冲击波前沿几乎瞬时；对起振段的分析是第一证据
回声拖尾 — ——爆炸声经建筑与地形反射；衰减的回声模式是第二重、与环境相关的指纹
与相似声的区分 — ——烟花上升更慢、带哨音拖尾；汽车回火是干净脉冲串、缺少复杂回声
一个行业诚实说明：鞭炮与枪声的区分是公认难题。多麦克风协同与跨节点事件聚合，是把可靠性做上去的现实路径。
识别方法：预处理 → 特征提取 → 算法
1. 冲击事件——上升沿触发
2. 特征验证——瞬态指纹 + 回声结构
3. 多麦克风协同定位（可选）——多节点到达时差估计事件点位
4. 推送与平台联动——指挥中心弹窗、地图标注、画面调取、工单创建
全部判定在边缘设备完成；音频默认不出设备。
城市级部署
城市级铺开是系统工程——六步路径：
1. 点位勘察——重点区域与噪声摸底
2. 设备选型与安装——高度、朝向、供电
3. 声学标定——逐点基线噪声与灵敏度校准
4. 联网联调——专网或蜂窝回传通道
5. 平台接入——事件接口、地图、工单
6. 日常运维——在线率监控、误报复盘、点位优化
先做试点点位群验证，再规模化推广。
边缘感知层 — ——本地判定枪声与上报策略
网络传输层 — ——有线/4G/5G 回传，断网缓存补传
平台层（可私有化） — ——事件汇聚、多点位关联、存储、开放接口
应用层 — ——指挥平台、值守端、工单、数据看板
点位集中在路口、学校与商圈；典型安装 4–6 米高度、避开强噪声源、按覆盖分层规划间距。
阶段：P1 试点（2–4 周）→ P2 扩展（2–3 月）→ P3 全域与长期运营。点位在线率目标 ≥99%；事件到平台 ≤5 秒。
校园与商圈行业方案
校园与商圈有共同的结构性缺口：大片开阔区域无法靠人眼持续看守。
1. 声学事件——边缘判定 + 点位标注
2. 值守端弹窗——时间、位置、片段引用
3. 画面复核——就近摄像头自动调取
4. 预案启动——巡逻出动、广播、报警联动
5. 现场处置——状态回传
6. 记录与复盘——归档演练
"先复核再出动"原则，让安保力量不被误报牵动。
人工发现需要数分钟到数十分钟；声学感知秒级送达——且提供可回溯可演练的记录。
准确率与性能
运行平台与硬件要求
感知节点本地运行 0.2–1MB（INT8）模型；节点典型杆装，PoE 或太阳能/电池供电；通过专网光纤或 LTE/5G 回传。
C 接口与嵌入式集成
「枪声」识别库提供简洁的流式 C 接口：调用方只需持续送入 16kHz 单声道 PCM，拼帧、Mel 预处理与模型推理全部在内部完成，帧级概率经报警策略聚合成「枪声事件」回调输出。
完整接口声明（gunshot_detect.h）：
/**
* gunshot_detect.h — 枪声识别统一接口
*
* 封装 Mel 预处理 + 推理引擎 + 报警策略, 内部模型消费线程处理音频。
* 与录音模块 (audio_capture.h) 相互独立: 调用者自行决定音频来源
* (录音回调 / wav 文件 / 网络流), 通过 gunshot_detect_feed 送入, 数据任意大小。
*
* 用法 (实时录音模式):
* gunshot_detect_t *d = gunshot_detect_create(mgk_path, NULL, NULL);
* gunshot_detect_set_listener(d, on_frame, on_onset, on_offset, NULL);
* gunshot_detect_start(d); // 启动内部模型消费线程
* audio_capture_start(rec, capture_cb, d); // 录音回调里调 gunshot_detect_feed
* ...
* gunshot_detect_stop(d); // 排空缓冲, 停止线程
* gunshot_detect_destroy(d);
*
* 用法 (wav 文件模式):
* gunshot_detect_t *d = gunshot_detect_create(mgk_path, NULL, NULL);
* gunshot_detect_set_listener(d, on_frame, on_onset, on_offset, NULL);
* gunshot_detect_start(d);
* 循环读文件: gunshot_detect_feed(d, pcm, n); // 任意数据大小
* gunshot_detect_stop(d);
* gunshot_detect_destroy(d);
*/
#ifndef GUNSHOT_DETECT_H
#define GUNSHOT_DETECT_H
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* 识别事件 (报警策略输出, 用于事件结束回调) */
typedef struct {
float start_time; /* 事件开始时间 (秒) */
float end_time; /* 事件结束时间 (秒) */
float confidence; /* 事件置信度 */
float max_confidence; /* 事件内最大帧置信度 */
int frame_count; /* 事件持续帧数 */
} gunshot_detect_event_t;
/* 帧级回调: 每帧识别结果 (模型线程内执行) */
typedef void (*gunshot_detect_frame_cb_t)(float gunshot_prob, float timestamp,
void *user_data);
/* 事件开始回调: 策略判定枪声事件开始, 只有开始时间 */
typedef void (*gunshot_detect_onset_cb_t)(float start_time, void *user_data);
/* 事件结束回调: 策略判定枪声事件结束 (或停止识别时未结束的事件), 完整事件信息 */
typedef void (*gunshot_detect_offset_cb_t)(const gunshot_detect_event_t *event,
void *user_data);
typedef struct gunshot_detect_s gunshot_detect_t;
/* 创建/销毁; alarm_name/alarm_params 可传 NULL (用默认策略及参数) */
gunshot_detect_t *gunshot_detect_create(const char *mgk_path, /* 模型文件路径 (必填) */
const char *alarm_name, /* 报警策略名, NULL=默认 */
const char *alarm_params); /* 策略参数 key=val,key=val, NULL=默认 */
void gunshot_detect_destroy(gunshot_detect_t *det);
/* 设置事件回调 (create 后调用, 也可在运行中调整); 不需要的回调传 NULL */
void gunshot_detect_set_listener(gunshot_detect_t *det,
gunshot_detect_frame_cb_t on_frame,
gunshot_detect_onset_cb_t on_onset,
gunshot_detect_offset_cb_t on_offset,
void *user_data);
/* 启动/停止识别: 启动内部模型消费线程 / 排空缓冲后停止线程 */
int gunshot_detect_start(gunshot_detect_t *det);
void gunshot_detect_stop(gunshot_detect_t *det);
int gunshot_detect_is_running(gunshot_detect_t *det);
/* 设置事件识别策略 (可在运行中调整) */
int gunshot_detect_set_alarm(gunshot_detect_t *det, const char *alarm_name,
const char *alarm_params);
/* 送入 PCM 数据 (16bit 单声道 16kHz), 线程安全, 任意数据大小 */
int gunshot_detect_feed(gunshot_detect_t *det, const int16_t *pcm, int num_samples);
#ifdef __cplusplus
}
#endif
#endif /* GUNSHOT_DETECT_H */
最简 wav 推理示例（节选，完整文件位于 SDK 的 src/gunshotDetect/c/gunshot_demo.c）：
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include "gunshot_detect.h"
#define DEFAULT_MGK "gunshot_detect_v7.mgk" /* 模型文件 */
#define DEFAULT_WAV "test_gunshot.wav" /* 16kHz 单声道 16bit PCM */
#define FEED_CHUNK 16000 /* 每次送入 1 秒音频 */
/* 帧级回调: 每帧输出枪声概率 (约 1 秒一帧) */
static void on_frame(float gunshot_prob, float timestamp, void *user_data)
{
(void)user_data;
printf("%8.2fs gunshot=%.4f\n", timestamp, gunshot_prob);
}
/* 事件开始回调: 策略判定枪声事件开始 */
static void on_onset(float start_time, void *user_data)
{
(void)user_data;
printf("[EVENT] gunshot start at %.2fs\n", start_time);
}
/* 事件结束回调: 应用层可据此做后续统计或分级响应 */
static void on_offset(const gunshot_detect_event_t *ev, void *user_data)
{
(void)user_data;
printf("[EVENT] gunshot end at %.2fs (dur=%.2fs, conf=%.3f, frames=%d)\n",
ev->end_time, ev->end_time - ev->start_time,
ev->confidence, ev->frame_count);
}
static int read_wav_pcm(const char *path, int16_t **pcm, int *n, int *sr); /* 完整实现见源文件 */
int main(void)
{
gunshot_detect_t *det;
int16_t *pcm = NULL;
int num_samples = 0, sample_rate = 0;
int pos;
if (read_wav_pcm(DEFAULT_WAV, &pcm, &num_samples, &sample_rate) != 0)
return 1;
/* 1. 创建识别器: 模型文件 + 默认报警策略 (NULL) */
det = gunshot_detect_create(DEFAULT_MGK, NULL, NULL);
if (!det) return 1;
/* 2. 注册回调 (均为可选) */
gunshot_detect_set_listener(det, on_frame, on_onset, on_offset, NULL);
/* 3. 启动内部模型消费线程 */
gunshot_detect_start(det);
/* 4. 分块送入 PCM; 实时录音时改在录音回调里 feed */
for (pos = 0; pos < num_samples; pos += FEED_CHUNK) {
int n = num_samples - pos;
if (n > FEED_CHUNK) n = FEED_CHUNK;
gunshot_detect_feed(det, pcm + pos, n);
}
/* 5. 停止并销毁 */
gunshot_detect_stop(det);
gunshot_detect_destroy(det);
free(pcm);
return 0;
}
编译与运行（示例）：
$(CC) gunshot_demo.c -I. -L. -lgunshotdetect -lpthread -lm -o gunshot_demo
./gunshot_demo结语
枪声检测是最难的瞬态识别，也是最有价值的瞬态识别。我们提供在线试用与部署方法论支持。