> For the complete documentation index, see [llms.txt](https://portal-integracao.intelbras.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://portal-integracao.intelbras.com.br/cameras-and-gravadores/integracao-api-cftvip-e-mibo/cameras-e-gravadores/gestao-de-audio.md).

# Gestão de Áudio

Integração de áudio: canais I/O (getCollect), stream G.711A (audio.cgi getAudio/postAudio, single/multipart), volume (AudioOutputVolume), análise (AudioAnalyseManager) e playback (Speak).

## Dicas & Boas Práticas <a href="#dicas-and-boas-praticas" id="dicas-and-boas-praticas"></a>

* Sempre que disponível, **prefira o modo Webhook (Push ativo)** para o recebimento de eventos.
* Utilize **HTTPS em conjunto com HTTP Digest Authentication** para garantir maior segurança nas integrações com o dispositivo.
* Valide corretamente todos os **eventos, imagens e payloads JSON** recebidos, verificando estrutura, tipos de dados e campos obrigatórios.
* Evite o uso de ferramentas como **Postman ou Insomnia** para APIs que utilizam conexões persistentes ou streaming em tempo real, pois essas ferramentas não oferecem suporte adequado a esse tipo de comunicação.
* Implemente **tratamento de exceções, controle de timeout e mecanismos de reconexão**, garantindo maior estabilidade e confiabilidade do sistema.
* Para fluxos de áudio contínuos, assegure o **encerramento correto das conexões**, evitando consumo excessivo de recursos no dispositivo e no cliente.

***

### Tabela de Parâmetros

<table><thead><tr><th width="198">Name</th><th width="110.66668701171875">Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>Configuration</td><td>object</td><td>Configuração de análise do canal de áudio</td><td>—</td></tr><tr><td>AudioChannel</td><td>uint32</td><td>Número do canal de áudio (local quando não é Internet)</td><td><code>0</code></td></tr><tr><td>Rules</td><td>object[]</td><td>Regras de análise</td><td>—</td></tr><tr><td>Class</td><td>char[64]</td><td>Categoria da regra</td><td><code>"&#x3C;ClassType>"</code></td></tr><tr><td>Type</td><td>char[64]</td><td>Tipo da regra</td><td><code>"&#x3C;RuleType>"</code></td></tr><tr><td>Id</td><td>uint</td><td>ID da regra (0 = auto)</td><td><code>0</code></td></tr><tr><td>Name</td><td>char[64]</td><td>Nome da regra</td><td><code>"Rule01"</code></td></tr><tr><td>Enable</td><td>bool</td><td>Habilita a regra</td><td><code>true</code></td></tr><tr><td>PresetID</td><td>uint32</td><td>ID do preset</td><td><code>0</code></td></tr><tr><td>EventHandler</td><td>object</td><td>Linkagem de eventos da regra</td><td>—</td></tr><tr><td>TimeSection</td><td>char[8][6][20]</td><td>Período de alarme</td><td><code>[["1 00:00:00-08:00:00"]]</code></td></tr><tr><td>RecordEnable</td><td>bool</td><td>Habilita gravação</td><td><code>true</code></td></tr><tr><td>RecordChannels</td><td>int[]</td><td>Lista de canais de gravação</td><td><code>[0,1,2]</code></td></tr><tr><td>RecordLatch</td><td>int</td><td>Delay de gravação (10–300s)</td><td><code>10</code></td></tr><tr><td>AlarmOutEnable</td><td>bool</td><td>Habilita saída de alarme</td><td><code>true</code></td></tr><tr><td>AlarmOutChannels</td><td>int[]</td><td>Canais de saída de alarme</td><td><code>[1,4]</code></td></tr><tr><td>AlarmOutLatch</td><td>int</td><td>Delay da saída de alarme (1–300s)</td><td><code>10</code></td></tr><tr><td>SnapshotEnable</td><td>bool</td><td>Habilita snapshot</td><td><code>true</code></td></tr><tr><td>SnapshotChannels</td><td>int[]</td><td>Canais de snapshot</td><td><code>[2,4]</code></td></tr><tr><td>MailEnable</td><td>bool</td><td>Envio de e-mail</td><td><code>true</code></td></tr><tr><td>Dejitter</td><td>int</td><td>Tempo de dejitter (0–600s)</td><td><code>0</code></td></tr><tr><td>BeepEnable</td><td>bool</td><td>Habilita buzzer</td><td><code>true</code></td></tr><tr><td>Delay</td><td>uint</td><td>Delay do evento (0–300s)</td><td><code>30</code></td></tr><tr><td>ExAlarmOutEnable</td><td>bool</td><td>Habilita saída de alarme estendida</td><td><code>true</code></td></tr><tr><td>ExAlarmOutChannels</td><td>int[]</td><td>Canais de alarme estendido</td><td><code>[2,3]</code></td></tr><tr><td>LightingLink</td><td>object</td><td>Linkagem de iluminador PTZ</td><td>—</td></tr><tr><td>Enable</td><td>bool</td><td>Habilita iluminação</td><td><code>true</code></td></tr><tr><td>FilckerLightType</td><td>enum char[32]</td><td>Tipo de luz (WhiteLight / RedBlueLight)</td><td><code>"WhiteLight"</code></td></tr><tr><td>LightLinkType</td><td>enum char[32]</td><td>Tipo de iluminação (Filcker / KeepLighting)</td><td><code>"Filcker"</code></td></tr><tr><td>FilckerIntervalTime</td><td>float</td><td>Intervalo de piscar (0.1s)</td><td><code>0.5</code></td></tr><tr><td>FilckerTimes</td><td>int</td><td>Número de piscadas</td><td><code>5</code></td></tr><tr><td>LightDuration</td><td>uint</td><td>Duração da luz (s)</td><td><code>10</code></td></tr><tr><td>LightBright</td><td>uint</td><td>Brilho da luz</td><td><code>50</code></td></tr><tr><td>PtzLink</td><td>object[][]</td><td>Linkagem PTZ</td><td><code>[["Preset",3,0,0,0]]</code></td></tr><tr><td>PtzLinkEnable</td><td>bool</td><td>Habilita PTZ Link</td><td><code>true</code></td></tr><tr><td>SnapshotPeriod</td><td>int</td><td>Intervalo de frames</td><td><code>3</code></td></tr><tr><td>SnapshotTimes</td><td>int</td><td>Quantidade de snapshots</td><td><code>5</code></td></tr><tr><td>VoiceEnable</td><td>bool</td><td>Habilita aviso por voz</td><td><code>true</code></td></tr><tr><td>Voice</td><td>object</td><td>Configuração de voz</td><td>—</td></tr><tr><td>Channels</td><td>int[]</td><td>Canais de áudio</td><td><code>[1,2]</code></td></tr><tr><td>AudioFileName</td><td>char[256]</td><td>Caminho do áudio</td><td><code>"/mnt/alarm.g711a"</code></td></tr><tr><td>PlayTimes</td><td>uint</td><td>Repetições do áudio</td><td><code>3</code></td></tr><tr><td>LinkTime</td><td>uint</td><td>Tempo de execução (s)</td><td><code>30</code></td></tr><tr><td>Interval</td><td>uint</td><td>Intervalo de reprodução (s)</td><td><code>30</code></td></tr><tr><td>Global</td><td>object</td><td>Configuração global</td><td>—</td></tr><tr><td>ClassList</td><td>char[32][64]</td><td>Lista de negócios válidos</td><td><code>["SoundDetect"]</code></td></tr><tr><td>Module</td><td>object</td><td>Configuração do módulo</td><td>—</td></tr><tr><td>Scene</td><td>object[]</td><td>Configuração por cena</td><td>—</td></tr><tr><td>State</td><td>uint32</td><td>Estado da análise (0:não suporta / 1:suporta)</td><td><code>1</code></td></tr><tr><td>PresetID</td><td>int32</td><td>ID do preset</td><td><code>0</code></td></tr><tr><td>AudioChannel</td><td>int32</td><td>Número do canal de áudio</td><td><code>0</code></td></tr><tr><td>DeviceID</td><td>char[128]</td><td>ID do dispositivo</td><td><code>"12345678"</code></td></tr></tbody></table>

***

### Limitação de Conexões Simultâneas

* O dispositivo pode limitar o número de:
  * Streams de áudio simultâneos
  * Sessões POST de envio de áudio
* Múltiplas conexões podem causar:
  * Falha na abertura de nova sessão
  * Interrupção de stream ativo
  * Alto uso de CPU

**Boa prática:**

* Encerrar conexões corretamente após uso.
* Evitar múltiplos clientes enviando áudio ao mesmo tempo no mesmo canal.

***

### Considerações para SmartSoundDetect

* Sensibilidade alta → mais falsos positivos
* Threshold baixo → mais eventos gerados
* Ambientes com ruído constante devem ajustar:
  * Sensitive
  * TimesThreshold
* Sempre testar:
  * Em ambiente real
  * Com ruído de fundo típico

***

### Obter Números dos Canais de Entrada de Áudio

**Tópico:** Este endpoint permite obter a **quantidade de canais de entrada de áudio disponíveis** no dispositivo, indicando quantos canais podem ser utilizados para captura de áudio.

* Método: `GET /cgi-bin/devAudioInput.cgi?action=getCollect`

**Exemplo**:

```http
http://<ip>/cgi-bin/devAudioInput.cgi?action=getCollect
```

**Resposta:**

```
result=1 
```

### Obter Números dos Canais de Saída de Áudio

**Tópico:** Este endpoint permite obter a **quantidade de canais de saída de áudio disponíveis** no dispositivo. A resposta indica o número total de canais que podem ser utilizados para reprodução de áudio.

* Método: `GET /cgi-bin/devAudioOutput.cgi?action=getCollect`

**Exemplo**:

```http
http://<ip>/cgi-bin/devAudioOutput.cgi?action=getCollect
```

**Resposta:**

```
result=2
```

### Transmitir Áudio Posteriormente

**Tópico:** Envie o fluxo de áudio para o dispositivo, a solicitação é muito longa e o cliente continua enviando dados de áudio. Se o cliente quiser parar, basta fechar a conexão.

* Método: `POST /cgi-bin/audio.cgi?action=postAudio`

**Exemplo (singlepart)**:

```powershell
"POST http://<ip>/cgi-bin/audio.cgi?action=postAudio&httptype=singlepart&channel=1 HTTP/
1.1 
User-Agent: client/1.0 
Content-Type: Audio/G.711A 
Content-Length: 9999999 
 
<Audio data> 
<Audio data> 
… "
```

**Exemplo (multipart)**:

<pre class="language-powershell"><code class="lang-powershell"><strong>"POST http://&#x3C;ip>/cgi-bin/audio.cgi?action=postAudio&#x26;httptype=multipart&#x26;channel=1 HTTP/
</strong>1.1 
User-Agent: client/1.0 
Content-Type: multipart/x-mixed-replace; boundary=&#x3C;boundary> 
 --&#x3C;boundary> 
Content-Type: Audio/G.711A 
Content-Length: 800 
 
&#x3C;Audio data> --&#x3C;boundary> 
Content-Type: Audio/G.711A 
Content-Length: 800 
 
&#x3C;Audio data> --&#x3C;boundary> 
… 
</code></pre>

**Resposta:**

```http
(N/A) 
//não possui parâmetros estruturados
```

### Obter Fluxo de Áudio

**Tópico:** Este endpoint permite obter o **fluxo de áudio em tempo real** do dispositivo para um canal específico, retornando os dados de áudio de forma contínua nos formatos **singlepart** ou **multipart**, conforme o tipo de requisição informado.

* Método: `GET /cgi-bin/audio.cgi?action=getAudio`

**Exemplo**:

```http
http://<ip>/cgi-bin/audio.cgi?action=getAudio&httptype=singlepart&channel=1
```

**Resposta (singlepart)**:

```http
200 OK HTTP/1.1 
Server: device/1.0 
Content-Type: Audio/G.711A 
Content-Length: 9999999 
 
<Audio data> 
<Audio data> 
… 
```

**Resposta (multipart)**:

```http
200 OK HTTP/1.1 
Server: device/1.0 
Content-Type: multipart/x-mixed-replace; boundary=<boundary> 
 --<boundary> 
Content-Type: Audio/G.711A 
Content-Length: 800 
 
<Audio data> --<boundary> 
Content-Type: Audio/G.711A 
Content-Length: 800 

<Audio data> --<boundary> 
… 
```

### Controle de Volume

**Tópico:** Permite consultar e configurar os níveis de volume dos canais de saída de áudio do dispositivo, ajustando individualmente o volume de cada canal.

* Método: `GET /cgi-bin/configManager.cgi?action=getConfig&name=AudioOutputVolume`
* **Exemplo de resposta**:

  ```
  table.AudioOutputVolume[0]=80 
  table.AudioOutputVolume[1]=50 
  … 
  ```

**Exemplo**:

```http
http://<ip>/cgi-bin/configManager.cgi?action=setConfig&AudioOutputVolume[0]=80&AudioOut
putVolume[1]=50
```

**Resposta:**

```
OK
```

### Obter Configurações de Análise do Áudio Especificado

**Tópico:** Obtém as configurações de análise de áudio do canal especificado, incluindo regras, parâmetros e estado da análise associados ao canal.

* Método: `POST /cgi-bin/api/AudioAnalyseManager/getConfig`

**Exemplo**:

```powershell
  "{ 
 "PresetID": 0, 
 "AudioChannel": 0, 
 "DeviceID": "12345678" 
}"
```

**Resposta:**

```json
{ 
 "Config": { 
  "AudioChannel": 0,  
  "Global": { 
   "ClassList": [],  
   "Detail": null,  
   "Module": null 
  },  
  "Rules": [ 
   { 
    "Class": "SmartSoundDetect",  
    "Config": { 
     "Sensitive": 5,  
     "TimesThreshold": 2,  
     "Types": [ 
       "AudioCrashingGlass",  
       "AudioScream",  
       "AudioGunshot",  
       "AudioExplosion" 
     ] 
    },  
    "Enable": false,  
    "EventHandler": { 
     "TourEnable": false,  
     "VoiceEnable": false, 
     ... 
    },  
    "Id": 1,  
    "Name": "SmartSoundDetect",  
    "PresetID": 0,  
 
    "Type": "SmartSoundDetect" 
   } 
  ],  
  "Scene": [ 
   { 
    "ClassList": [],  
    "Detail": null,  
    "Module": { 
     "SmartSoundDetect": { 
      "Threshold": 50 
     } 
    },  
    "PresetID": 0 
   } 
  ],  
  "State": 1 
 } 
} 
```

### Definir Configurações de Análise de Áudio do Canal

**Tópico:** Configure a análise da configuração do canal de áudio especificado.

* Método: `POST /cgi-bin/api/AudioAnalyseManager/setConfig`

**Exemplo**:

```json
  "{ 
 "AudioChannel": 0, 
 "DeviceID": "12345678", 
 "Config": { 
  "AudioChannel": 0, 
  "Global": { 
   "ClassList": [], 
   "Detail": null, 
   "Module": null 
  }, 
  "Rules": [ 
   { 
    "Class": "SmartSoundDetect", 
    "Config": { 
     "Sensitive": 6, 
     "TimesThreshold": 1, 
     "Types": [ 
      "AudioCrashingGlass", 
      "AudioScream", 
      "AudioGunshot", 
      "AudioExplosion" 
     ] 
    }, 
    "Enable": false, 
    "EventHandler": { 
     "TourEnable": false, 
     "VoiceEnable": false, 
     ... 
    }, 
    "Id": 1, 
    "Name": "SmartSoundDetect", 
    "PresetID": 0, 
    "Type": "SmartSoundDetect" 
   } 
  ], 
  "Scene": [ 
   { 
    "ClassList": [], 
    "Detail": null, 
    "Module": { 
     "SmartSoundDetect": { 
      "Threshold": 50 
     } 
    }, 
    "PresetID": 0 
   } 

  ], 
  "State": 1 
 } 
}"
```

**Resposta:**

```
{}
```

### Obter Configurações de Negócios Associadas ao Item Especificado

**Tópico:** Obtenha a configuração comercial relacionada ao canal de áudio especificado.

* Método: `POST /cgi-bin/api/AudioAnalyseManager/getClassConfig`

**Exemplo**:

```powershell
 {
    "Class": "SmartSoundDetect", 
    "PresetID": 0, 
    "AudioChannel": 0, 
    "DeviceID": "12345678" 
} 
```

**Resposta:**

```json
{ 
 "Config": { 
  "Global": { 
   "Detail": null 
  }, 
  "Module": { 
   "Threshold": 50 
  }, 
  "Rules": [ 
   { 
    "Class": "SmartSoundDetect", 
    "Config": { 
     "Sensitive": 6, 
     "TimesThreshold": 1, 
     "Types": [ 
      "AudioCrashingGlass", 
      "AudioScream", 
      "AudioGunshot", 
      "AudioExplosion" 
     ] 
    }, 
    "Enable": false, 
    "EventHandler": { 
     "TourEnable": false, 
     "VoiceEnable": false, 
     ... 
    }, 
    "Id": 1, 
    "Name": "SmartSoundDetect", 
    "PresetID": 0, 
    "Type": "SmartSoundDetect" 
   } 
  ], 
  "Scene": { 
   "Detail": null 
  } 
 } 
} 
```

### Definir a Configuração de Negócios Associadas ao Item Especificado

**Tópico:** Defina a configuração de análise do canal de áudio especificado.

* Método: `POST /cgi-bin/api/AudioAnalyseManager/setClassConfig`

**Exemplo**:

```powershell
 { 
 "Class": "SmartSoundDetect", 
 "AudioChannel": 0, 
 "DeviceID": "12345678", 
    "PresetID": 0, 
 "Config": { 
  "Global": { 
   "Detail": null 
  }, 
  "Module": { 
   "Threshold": 50 
  }, 
  "Rules": [ 
   { 
    "Class": "SmartSoundDetect", 
    "Config": { 
     "Sensitive": 6, 
     "TimesThreshold": 1, 
     "Types": [ 
      "AudioCrashingGlass", 
      "AudioScream", 
      "AudioGunshot", 
      "AudioExplosion" 
     ] 
    }, 
    "Enable": false, 
    "EventHandler": { 
     "TourEnable": false, 
     "VoiceEnable": false, 

     ... 
    }, 
    "Id": 1, 
    "Name": "SmartSoundDetect", 
    "PresetID": 0, 
    "Type": "SmartSoundDetect" 
   } 
  ], 
  "Scene": { 
   "Detail": null 
  } 
 } 
} 
 
```

**Resposta:**

```json
{}
```

### Configurações de parâmetros

| Name             | Type           | Descrição                                                                                                              | Exemplo        |
| ---------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------- |
| `Types`          | char\[32]\[32] | Tipos de som detectados                                                                                                | `["AudioCry"]` |
|                  |                | **Valores possíveis:** `AudioCry`, `AudioAlarm`, `AudioGunshot`, `AudioExplosion`, `AudioScream`, `AudioCrashingGlass` |                |
| `Sensitive`      | uint32         | Sensibilidade de detecção. Intervalo: `[1, 10]`                                                                        | `5`            |
| `TimesThreshold` | uint32         | Limite de ocorrências. Intervalo: `[1, 5]`                                                                             | `2`            |

#### Configuração do AudioAnalyseModule

| Name        | Type   | Descrição                                           | Exemplo |
| ----------- | ------ | --------------------------------------------------- | ------- |
| `Threshold` | uint32 | Limite de intensidade do som. Intervalo: `[1, 100]` | `50`    |

### Reproduzir Áudio Especificado no Dispositivo

**Tópico:** Reproduz um arquivo de áudio específico armazenado no dispositivo, permitindo definir o número de vezes que o áudio será reproduzido.

* Método: `POST /cgi-bin/api/Speak/startPlayByTime`

**Exemplo**:

```json
  {
"Path":"/Audio_Path",
"FileName":"alarm.wav",
"PlayTimes":1
}
```

```json
{ 
  "Status" : "OK" 
}
```

### Verificar Se o Buffer de Decodificação Está Vazio

**Tópico:** Verifica se o buffer de decodificação de áudio do canal especificado está vazio de acordo com o tipo de fluxo de áudio informado.

* Método: `POST /cgi-bin/api/devAudioDecode/empty`

**Exemplo**:

```json
{ 
    "channel": 0, 
    "sourceType": 0 
} 
```

```json
{ 
   "flag": true 
} 
```

***

### Considerações Técnicas Avançadas

* Dispositivos podem limitar conexões simultâneas de áudio.
* Envio contínuo de áudio deve respeitar o codec suportado (ex.: G.711A).
* Conexões não encerradas corretamente podem gerar:
  * Consumo excessivo de memória
  * Buffer travado
  * Latência acumulada
* Alterações em parâmetros de análise de áudio devem ser testadas previamente para evitar:
  * Falsos positivos
  * Perda de eventos críticos
* Recomenda-se monitorar uso de CPU ao ativar múltiplas regras de análise simultaneamente.

***

Notas finais:

* Endpoints de áudio que utilizam **streaming contínuo** não retornam respostas estruturadas em JSON, pois os dados são transmitidos em fluxo binário.
* Parâmetros marcados como **(N/A)** indicam que o endpoint não possui parâmetros estruturados de resposta, apenas status HTTP ou fluxo de dados.
* Antes de aplicar configurações em ambiente de produção, valide os parâmetros em **ambiente de testes** para evitar impactos no funcionamento do dispositivo.
* Para configurações de análise de áudio, alterações incorretas de sensibilidade e limiares podem gerar **falsos positivos ou perda de eventos relevantes**.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://portal-integracao.intelbras.com.br/cameras-and-gravadores/integracao-api-cftvip-e-mibo/cameras-e-gravadores/gestao-de-audio.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.