# `sunau` — Lê e escreve arquivos AU da Sun

Código-fonte: Lib/sunau.py

Obsoleto desde a versão 3.11: O módulo `sunau` foi descontinuado (veja PEP 594 para mais detalhes).

O módulo `sunau` fornece uma interface conveniente para o formato de som AU da Sun. Observe que este módulo é compatível com a interface dos módulos `aifc` e `wave`.

Um arquivo de áudio consiste em um cabeçalho seguido pelos dados. Os campos do cabeçalho são:

Campo | Conteúdo
--- | ---
palavra mágica | O `.snd` da quatro bytes.
tamanho do cabeçalho | Tamanho do cabeçalho, incluindo informações, em bytes.
tamanho dos dados | Tamanho físico dos dados, em bytes.
codificação | Indica como as amostras de áudio estão codificadas.
taxa de amostra | A taxa de amostra.
nº de canais | O número de canais nas amostras.
informações | Uma string ASCII dando uma descrição do arquivo de áudio (preenchendo com bytes nulos).

Além do campo de informações, todos os campos de cabeçalho têm 4 bytes de tamanho. Eles são todos inteiros sem sinal de 32 bits, codificados na ordem de bytes big-endian.

O módulo `sunau` define as seguintes funções:

`sunau.``open`(file, mode)

  Se file for uma string, abra o arquivo com esse nome; caso contrário, trata-o como um objeto arquivo ou similar que pode ser procurado. mode pode ser qualquer um entre

  `'r'`

    Modo somente para leitura.

  `'w'`

    Modo somente para escrita.

  Observe que ele não permite arquivos de leitura e escrita.

  Um mode de `'r'` retorna um objeto `AU_read`, enquanto um mode de `'w'` ou `'wb'` retorna um objeto `AU_write`.

O módulo `sunau` define a seguinte exceção:

exception `sunau.``Error`

  Um erro levantado quando algo é impossível devido às especificações AU da Sun ou deficiência de implementação.

O módulo `sunau` define os seguintes itens de dados:

`sunau.``AUDIO_FILE_MAGIC`

  Um número inteiro com o qual todo arquivo AU da Sun válido começa, armazenado no formato big-endian. Esta é a string `.snd` interpretada como um inteiro.

`sunau.``AUDIO_FILE_ENCODING_MULAW_8`
`sunau.``AUDIO_FILE_ENCODING_LINEAR_8`
`sunau.``AUDIO_FILE_ENCODING_LINEAR_16`
`sunau.``AUDIO_FILE_ENCODING_LINEAR_24`
`sunau.``AUDIO_FILE_ENCODING_LINEAR_32`
`sunau.``AUDIO_FILE_ENCODING_ALAW_8`

  Valores do campo de codificação do cabeçalho de AU que são suportados por este módulo.

`sunau.``AUDIO_FILE_ENCODING_FLOAT`
`sunau.``AUDIO_FILE_ENCODING_DOUBLE`
`sunau.``AUDIO_FILE_ENCODING_ADPCM_G721`
`sunau.``AUDIO_FILE_ENCODING_ADPCM_G722`
`sunau.``AUDIO_FILE_ENCODING_ADPCM_G723_3`
`sunau.``AUDIO_FILE_ENCODING_ADPCM_G723_5`

  Valores conhecidos adicionais de codificação do cabeçalho de AU, mas que não são suportados por este módulo.

## Objetos AU_read

Objetos AU_read, conforme retornado por `open()` acima, têm os seguintes métodos:

`AU_read.``close`()

  Fecha o fluxo e torna a instância inutilizável. (Isso é chamado automaticamente na exclusão.)

`AU_read.``getnchannels`()

  Retorna o número de canais de áudio (1 para mono, 2 para estéreo).

`AU_read.``getsampwidth`()

  Retorna a largura da amostra em bytes.

`AU_read.``getframerate`()

  Retorna a frequência de amostragem.

`AU_read.``getnframes`()

  Retorna o número de quadros de áudio.

`AU_read.``getcomptype`()

  Retorna o tipo de compressão. Os tipos de compressão suportados são `'ULAW'`, `'ALAW'` e `'NONE'`.

`AU_read.``getcompname`()

  Versão legível de `getcomptype()`. Os tipos suportados têm os respectivos nomes `'CCITT G.711 u-law'`, `'CCITT G.711 A-law'` e `'not compressed'`.

`AU_read.``getparams`()

  Retorna uma `namedtuple()` `(nchannels, sampwidth, framerate, nframes, comptype, compname)`, equivalente à saída dos métodos `get*()`.

`AU_read.``readframes`(n)

  Lê e retorna no máximo n quadros de áudio, como um objeto `bytes`. Os dados serão retornados em formato linear. Se os dados originais estiverem no formato u-LAW, eles serão convertidos.

`AU_read.``rewind`()

  Volta o ponteiro do arquivo para o início do fluxo de áudio.

Os dois métodos a seguir definem um termo “posição” que é compatível entre eles e é dependente da implementação.

`AU_read.``setpos`(pos)

  Define o ponteiro do arquivo para a posição especificada. Apenas os valores retornados de `tell()` devem ser usados para pos.

`AU_read.``tell`()

  Retorna a posição atual do ponteiro do arquivo. Observe que o valor retornado não tem nada a ver com a posição real no arquivo.

As duas funções a seguir são definidas para compatibilidade com o `aifc`, e não fazem nada de interessante.

`AU_read.``getmarkers`()

  Retorna `None`.

`AU_read.``getmark`(id)

  Levanta um erro.

## Objetos AU_write

Objetos AU_write, conforme retornado por `open()` acima, têm os seguintes métodos:

`AU_write.``setnchannels`(n)

  Define o número de canais.

`AU_write.``setsampwidth`(n)

  Define a largura da amostra (em bytes).

  Alterado na versão 3.4: Adicionado suporte para amostras de 24 bits.

`AU_write.``setframerate`(n)

  Define a taxa de quadros.

`AU_write.``setnframes`(n)

  Define o número de quadros. Isso pode ser alterado posteriormente, quando e se mais quadros forem gravados.

`AU_write.``setcomptype`(type, name)

  Define o tipo de compactação e a descrição. Somente `'NONE'` e `'ULAW'` são suportados na saída.

`AU_write.``setparams`(tuple)

  A tuple deve ser `(nchannels, sampwidth, framerate, nframes, comptype, compname)`, com valores válidos para os métodos `set*()`. Define todos os parâmetros.

`AU_write.``tell`()

  Retorna a posição atual no arquivo, com as mesmas observações dos métodos `AU_read.tell()` e `AU_read.setpos()`.

`AU_write.``writeframesraw`(data)

  Escreve quadros de áudio, sem corrigir nframes.

  Alterado na versão 3.4: Todo objeto bytes ou similar agora é aceito.

`AU_write.``writeframes`(data)

  Escreve quadros de áudio e certifica-se de que nframes esteja correto.

  Alterado na versão 3.4: Todo objeto bytes ou similar agora é aceito.

`AU_write.``close`()

  Certifica-se de que nframes está correto e fecha o arquivo.

  Este método é chamado após a exclusão.

Observe que é inválido definir qualquer parâmetro após chamar `writeframes()` ou `writeframesraw()`.