Fonte de áudio

Família: Áudio · Grupo: Reprodução · Identificador: astra.audio.source · Payload: 2

Escopo da evidência

Este contrato foi extraído dos descritores compilados da engine, incluindo padrões resolvidos. A presença do contrato não substitui a validação do comportamento em um aparelho.

Para que usar

Clipe de projeto com reprodução e espaço acústico

Atribua um clipe do projeto ao Audio Source e confira reprodução, volume, mute e bus. Escolha escuta e espacialização; prioridade decide o listener efetivo.

Criar e configurar

Hierarquia → selecione o objeto → Inspector → Adicionar componente → Áudio / Reprodução → Fonte de áudio.

O schema permite uma única instância desse tipo por objeto. A fachada C# correspondente é Astra.Components.AudioSource.

Atribua o clipe WAV pelo seletor de recurso e o Bus pelo seletor de objeto. Esses recursos não são valores numéricos. Mistura espacial 0 = 2D e 1 = 3D. Até 32 vozes são reais; as menos prioritárias podem ficar virtuais. Streaming usa leitura progressiva para músicas longas. MP3/OGG não estão incluídos.

Guia relacionado: Mixer, streaming e vozes

Exemplo de uso

Um Audio Source e um Audio Listener: toque um clipe, altere volume/mute e depois compare estéreo com 3D movendo a fonte.

Dependências

Nenhuma regra adicional declarada no schema deste componente.

Conflitos

Nenhuma regra adicional declarada no schema deste componente.

Edição e ciclo de vida

Operação	Contrato
Adicionar/remover em Play	ponto seguro
Alterar propriedades em Play	ponto seguro
Múltiplas instâncias	Não
Versão do payload	2

Alterações em ponto seguro são aplicadas entre passos da simulação. Um componente exigido por outro não pode ser removido enquanto a dependência existir. Salvar a cena autoral e modificar o mundo de Play são operações distintas; veja Play e cena autoral.

Propriedades

Valores abaixo são resolvidos pelo descritor de um componente recém-criado. Campos por slot dependem dos recursos atribuídos. Um campo sem padrão significa que o descritor não fornece um valor independente de contexto.

Recursos do projeto

Estes seletores ficam no componente e não entram na contagem dos campos numéricos. Use recursos registrados do projeto; nome ou caminho externo não substitui uma referência válida.

Recurso	Onde	Tipo	Uso
Clipe WAV · clip	Inspector → Fonte de áudio → Som	audio_clip	Escolha um recurso compatível no seletor.

Som

Propriedade	Tipo / unidade	Padrão	Domínio
Volume volume	número	1	0 … 1
Prioridade priority	número	128	0 … 256
Ativo enabled	booleano	verdadeiro	verdadeiro | falso
Silenciar mute	booleano	falso	verdadeiro | falso
Carregamento loading	enumeração	Memória	Memória | Streaming
Bus bus	referência	Master	astra.audio.bus

Volume · volume

Onde: Inspector → Fonte de áudio → Som → Volume.

Uso e efeito: Ganho linear de áudio do consumidor correspondente; 0 silencia e 1 conserva ganho unitário.

Valor: 1 · Tipo: número · Domínio: 0 … 1.

Aceita tween numérico via contrato de propriedade.

Prioridade · priority

Onde: Inspector → Fonte de áudio → Som → Prioridade.

Uso e efeito: 0 é a prioridade mais importante. Ao exceder 32 vozes reais, as menos importantes podem ficar virtuais e conservar o progresso para retornar.

Valor: 128 · Tipo: número · Domínio: 0 … 256.

Ativo · enabled

Onde: Inspector → Fonte de áudio → Som → Ativo.

Uso e efeito: Ativa/desativa a participação do componente no sistema consumidor; não remove seus dados.

Valor: verdadeiro · Tipo: booleano · Domínio: verdadeiro | falso.

Silenciar · mute

Onde: Inspector → Fonte de áudio → Som → Silenciar.

Uso e efeito: Silencia sem remover o componente.

Valor: falso · Tipo: booleano · Domínio: verdadeiro | falso.

Carregamento · loading

Onde: Inspector → Fonte de áudio → Som → Carregamento.

Uso e efeito: Escolhe carregamento do clipe: Streaming lê progressivamente, em vez de presumir tudo em memória. WAV longo é importado para streaming; salve a cena após importar.

Valor: Memória · Tipo: enumeração · Domínio: Memória | Streaming.

Bus · bus

Onde: Inspector → Fonte de áudio → Som → Bus.

Uso e efeito: Destino de mixer da fonte.

Valor: Master · Tipo: referência · Domínio: astra.audio.bus.

Reprodução

Propriedade	Tipo / unidade	Padrão	Domínio
Velocidade / pitch pitch	número · ×	1	0.1 … 4
Início do loop loop_start	número · s	0	0 … 36000
Fim do loop loop_end	número · s	0	0 … 36000
Repetir loop	booleano	falso	verdadeiro | falso
Pedido playback	enumeração	Tocar	Parar | Tocar | Pausar

Velocidade / pitch · pitch

Onde: Inspector → Fonte de áudio → Reprodução → Velocidade / pitch.

Uso e efeito: Velocidade/pitch da reprodução; não altera o arquivo original.

Valor: 1 · Tipo: número · Unidade: × · Domínio: 0.1 … 4.

Aceita tween numérico via contrato de propriedade.

Início do loop · loop_start

Onde: Inspector → Fonte de áudio → Reprodução → Início do loop.

Uso e efeito: Início do trecho repetido, em segundos do clipe. Exige loop ligado e intervalo válido.

Valor: 0 · Tipo: número · Unidade: s · Domínio: 0 … 36000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Fim do loop · loop_end

Onde: Inspector → Fonte de áudio → Reprodução → Fim do loop.

Uso e efeito: Fim do trecho repetido, em segundos. Confira a duração real do WAV e início menor que fim.

Valor: 0 · Tipo: número · Unidade: s · Domínio: 0 … 36000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Repetir · loop

Onde: Inspector → Fonte de áudio → Reprodução → Repetir.

Uso e efeito: Repete a reprodução/percurso no fim.

Valor: falso · Tipo: booleano · Domínio: verdadeiro | falso.

Pedido · playback

Onde: Inspector → Fonte de áudio → Reprodução → Pedido.

Uso e efeito: Pedido persistido; consulte o estado real na nota do componente.

Valor: Tocar · Tipo: enumeração · Domínio: Parar | Tocar | Pausar.

Espaço

Propriedade	Tipo / unidade	Padrão	Domínio
Pan estéreo pan	número	0	-1 … 1
Distância mínima min_distance	número · m	1	0.01 … 100000
Distância máxima max_distance	número · m	100	0.02 … 100001
Decaimento rolloff_factor	número	1	0 … 10
Mistura espacial spatial_blend	número	1	0 … 1
Dimensão dimension	enumeração	2D / estéreo	2D / estéreo | 3D / espacial
Atenuação rolloff	enumeração	Inverso	Linear | Inverso | Exponencial

Pan estéreo · pan

Onde: Inspector → Fonte de áudio → Espaço → Pan estéreo.

Uso e efeito: Em 3D, vale para a parte 2D da mistura espacial

Valor: 0 · Tipo: número · Domínio: -1 … 1.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. Aceita tween numérico via contrato de propriedade.

Distância mínima · min_distance

Onde: Inspector → Fonte de áudio → Espaço → Distância mínima.

Uso e efeito: Distância próxima de referência da atenuação 3D.

Valor: 1 · Tipo: número · Unidade: m · Domínio: 0.01 … 100000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Distância máxima · max_distance

Onde: Inspector → Fonte de áudio → Espaço → Distância máxima.

Uso e efeito: Distância máxima de referência da atenuação 3D.

Valor: 100 · Tipo: número · Unidade: m · Domínio: 0.02 … 100001.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Decaimento · rolloff_factor

Onde: Inspector → Fonte de áudio → Espaço → Decaimento.

Uso e efeito: Fator de queda de ganho do modelo de atenuação.

Valor: 1 · Tipo: número · Domínio: 0 … 10.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Mistura espacial · spatial_blend

Onde: Inspector → Fonte de áudio → Espaço → Mistura espacial.

Uso e efeito: 0 usa apresentação 2D, 1 usa 3D; valores intermediários misturam. Confira Listener, distâncias e o recurso real.

Valor: 1 · Tipo: número · Domínio: 0 … 1.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. Aceita tween numérico via contrato de propriedade.

Dimensão · dimension

Onde: Inspector → Fonte de áudio → Espaço → Dimensão.

Uso e efeito: Seleciona áudio estéreo ou espacial conforme o domínio.

Valor: 2D / estéreo · Tipo: enumeração · Domínio: 2D / estéreo | 3D / espacial.

Atenuação · rolloff

Onde: Inspector → Fonte de áudio → Espaço → Atenuação.

Uso e efeito: Modelo de atenuação por distância.

Valor: Inverso · Tipo: enumeração · Domínio: Linear | Inverso | Exponencial.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Emissão

Propriedade	Tipo / unidade	Padrão	Domínio
Cone interno cone_inner	número · °	360	0 … 360
Cone externo cone_outer	número · °	360	0 … 360
Ganho fora do cone cone_gain	número	0	0 … 1
Doppler doppler	número · ×	1	0 … 4

Cone interno · cone_inner

Onde: Inspector → Fonte de áudio → Emissão → Cone interno.

Uso e efeito: Ângulo interno do cone acústico.

Valor: 360 · Tipo: número · Unidade: ° · Domínio: 0 … 360.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Cone externo · cone_outer

Onde: Inspector → Fonte de áudio → Emissão → Cone externo.

Uso e efeito: Ângulo externo do cone acústico.

Valor: 360 · Tipo: número · Unidade: ° · Domínio: 0 … 360.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Ganho fora do cone · cone_gain

Onde: Inspector → Fonte de áudio → Emissão → Ganho fora do cone.

Uso e efeito: Ganho fora da região interna do cone.

Valor: 0 · Tipo: número · Domínio: 0 … 1.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Doppler · doppler

Onde: Inspector → Fonte de áudio → Emissão → Doppler.

Uso e efeito: Fator do efeito Doppler.

Valor: 1 · Tipo: número · Unidade: × · Domínio: 0 … 4.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Roadmap deste componente

Áudio. Ampliar transporte, formatos, mixer e diagnóstico de backend. Seek não deve ser presumido como disponível porque há cursor de reprodução. Conferir saída física no aparelho é uma evidência separada.

Os campos acima pertencem ao contrato existente; novas funções dependem do fechamento da família. Não há datas individuais prometidas para cada propriedade.

Conferir na sua cena

1. Crie Fonte de áudio pelo fluxo indicado e resolva as dependências.
2. Altere uma propriedade por vez e observe o efeito esperado na cena.
3. Salve, reabra e confira os valores autorais.
4. Entre em Play e verifique o comportamento com os recursos reais do projeto.
5. Pare o Play e confira a cena autoral.

Este é um roteiro de conferência; não representa um teste executado nesta publicação.

Limitações da referência

A tabela cobre os tipos de propriedade disponíveis no descritor de reflexão. Não presume persistência de campos transitórios, equivalência com outras engines ou suporte em todos os aparelhos. Recursos, coleções e operações podem exigir APIs específicas.

Referência de arquitetura registrada pela engine: documentação oficial. Essa referência não representa paridade funcional.

Comandos e leituras em Play

Os IDs abaixo são operações nativas do componente existente. Não são novos botões de autoria. Use a fachada C# correspondente para nomes e assinaturas; Conexão de evento oferece as ações compatíveis no seletor. Confira o componente e o mundo vivos antes de chamar.

Operação / ID	Uso e efeito	Argumentos	Retorno
Tocar · play	Recomeça do início	Nenhum	nada
Pausar · pause	Congela o cursor	Nenhum	nada
Retomar · resume	Continua do cursor pausado	Nenhum	nada
Parar · stop	Interrompe e libera a voz	Nenhum	nada
Posicionar · seek	Move o cursor; aplicado pelo mixer	Posição: número (s)	nada
Virtual · is_virtual	Verdadeiro quando a voz passou do limite de vozes e é acompanhada sem tocar	Nenhum	booleano

Assinaturas da fachada AudioSource