O módulo winsound oferece acesso simples a recursos de áudio do Windows. Ele pode reproduzir sons do sistema, arquivos WAV, aliases registrados, sequências assíncronas e tons básicos gerados pelo speaker. É útil para notificações locais, ferramentas administrativas, protótipos, aplicações educacionais e pequenos programas que precisam de feedback sonoro sem instalar uma biblioteca externa.
Ele não é um motor de áudio completo. Não oferece mixagem multicanal, reprodução geral de MP3, streaming, edição, controle preciso de volume ou baixa latência. Além disso, está disponível apenas no Windows. Para aplicações portáveis ou multimídia avançada, use uma biblioteca dedicada.
Disponibilidade
Proteja o import quando o mesmo projeto também precisa funcionar em Linux ou macOS.
import sys
if sys.platform == "win32":
import winsound
else:
winsound = None
Uma aplicação pode oferecer notificações visuais quando o áudio não estiver disponível. Isso também melhora acessibilidade e evita que um som seja a única forma de comunicar um erro.
O primeiro beep
Beep(frequency, duration) produz um tom com frequência em hertz e duração em milissegundos.
import winsound
winsound.Beep(880, 200)
Os limites aceitos dependem da implementação do Windows. Valores inválidos geram erro. O beep bloqueia enquanto o tom é executado, portanto não deve ser usado em loops apertados ou na thread principal de uma interface gráfica quando a duração for longa.
Crie uma sequência de tons
Uma melodia simples pode ser representada por pares de frequência e duração.
import winsound
notas = [
(523, 150),
(659, 150),
(784, 250),
]
for frequencia, duracao in notas:
winsound.Beep(frequencia, duracao)
Isso é adequado para demonstrações, não para música profissional. Timing, timbre e polifonia são limitados.
Sons do sistema com MessageBeep
MessageBeep() reproduz um som associado a eventos do Windows. Constantes como MB_ICONASTERISK, MB_ICONEXCLAMATION, MB_ICONHAND, MB_ICONQUESTION e MB_OK indicam categorias conhecidas.
import winsound
winsound.MessageBeep(winsound.MB_ICONEXCLAMATION)
O usuário pode ter personalizado ou desativado esses sons. Não presuma que um evento sempre produzirá o mesmo áudio.
PlaySound para arquivos e aliases
PlaySound(sound, flags) é a função mais flexível. O primeiro argumento identifica um arquivo, um alias ou dados em memória, e as flags definem como interpretá-lo.
import winsound
winsound.PlaySound(
r"C:\Windows\Media\notify.wav",
winsound.SND_FILENAME,
)
Use uma string raw para caminhos Windows ou construa o caminho com pathlib.Path. Verifique a existência do arquivo antes da reprodução quando a ausência exigir uma mensagem específica.
Arquivos WAV
A API é orientada a sons compatíveis com o mecanismo tradicional do Windows, principalmente WAV. Não espere que um arquivo seja aceito apenas porque um player comum consegue abri-lo. Formato, codec, canais e parâmetros podem influenciar a compatibilidade.
Para MP3, OGG, FLAC ou streaming, escolha uma biblioteca de áudio apropriada.
Aliases do sistema
Com SND_ALIAS, o primeiro argumento é o nome de um evento sonoro registrado no Windows.
winsound.PlaySound(
"SystemAsterisk",
winsound.SND_ALIAS,
)
Aliases podem variar entre versões, configurações e idiomas. Tenha fallback e não dependa de um alias não documentado.
Reprodução assíncrona
SND_ASYNC inicia o som e retorna imediatamente.
winsound.PlaySound(
"alerta.wav",
winsound.SND_FILENAME | winsound.SND_ASYNC,
)
print("A aplicação continua")
A reprodução usa recursos globais do processo e do sistema. Um segundo som pode interromper ou substituir o anterior dependendo das flags e do ambiente.
Repetição com SND_LOOP
SND_LOOP repete o som. Ele deve ser combinado com reprodução assíncrona para que o programa consiga continuar e posteriormente interromper o loop.
winsound.PlaySound(
"alarme.wav",
winsound.SND_FILENAME | winsound.SND_ASYNC | winsound.SND_LOOP,
)
Um loop sem caminho de parada é uma experiência ruim. Sempre ofereça cancelamento e pare o som durante shutdown, exceção ou troca de tela.
Pare um som
Uma chamada com None interrompe a reprodução controlada por PlaySound().
winsound.PlaySound(None, 0)
Coloque a parada em um bloco finally quando o som for temporário.
try:
iniciar_alarme()
executar_tarefa()
finally:
winsound.PlaySound(None, 0)
Não interrompa outro som
SND_NOSTOP pede para a chamada falhar em vez de interromper um som já ativo. Isso pode ser útil quando notificações secundárias não devem substituir um alarme importante.
Trate a falha como estado normal, não como exceção fatal da aplicação.
Fallback quando o som não existe
SND_NODEFAULT impede que o Windows use um som padrão quando o som solicitado não é encontrado. Sem essa flag, a aplicação pode tocar algo diferente do esperado.
Escolha conscientemente entre silêncio, fallback próprio e som padrão do sistema.
Dados em memória
SND_MEMORY permite fornecer bytes de um WAV em memória.
from pathlib import Path
import winsound
dados = Path("alerta.wav").read_bytes()
winsound.PlaySound(dados, winsound.SND_MEMORY)
Esse modo não combina com todas as opções assíncronas. Também mantém os bytes na memória durante a reprodução. Limite o tamanho e não carregue arquivos não confiáveis sem validação.
Aplicações gráficas
Chamadas síncronas bloqueiam a thread atual. Em uma GUI, isso pode congelar botões e rendering. Use reprodução assíncrona ou despache a chamada para uma thread curta, mantendo o controle de cancelamento.
Não crie uma nova thread ilimitada para cada notificação. Um gerenciador de áudio central evita sobreposição e vazamento de recursos.
Serviços e sessões sem desktop
Um serviço Windows, tarefa agendada ou processo remoto pode não possuir sessão de áudio interativa. A chamada pode não ser ouvida pelo usuário esperado.
Para alertas operacionais, use também logs, e-mail, métricas ou notificações do sistema. Som local não é um canal confiável de monitoramento.
Volume e preferências
winsound não oferece um controle de volume por aplicação. O resultado depende do mixer, dispositivo ativo, políticas, modo silencioso e preferências do usuário.
Respeite uma opção para desativar sons. Não aumente volume nem repita alertas agressivamente para compensar silêncio.
Acessibilidade
Feedback sonoro deve ser acompanhado por texto, cor, ícone, vibração ou outro canal apropriado. Usuários podem não ouvir o som, estar em ambiente compartilhado ou usar tecnologias assistivas.
Também evite tons repentinos e muito longos. Permita testar a notificação e ajustar a preferência.
Segurança de caminhos
Não monte um caminho de áudio diretamente com entrada não confiável. Restrinja arquivos a um diretório conhecido e valide a resolução final.
from pathlib import Path
base = Path("sons").resolve()
candidato = (base / nome_arquivo).resolve()
if base not in candidato.parents:
raise ValueError("arquivo fora do diretório permitido")
Essa validação ajuda a evitar path traversal, mas permissões e symlinks também precisam ser considerados.
Erros e fallback
Falhas normalmente aparecem como RuntimeError. Capture a operação de áudio, registre contexto e continue somente quando o som for opcional.
try:
winsound.PlaySound("alerta.wav", winsound.SND_FILENAME)
except RuntimeError as erro:
registrar_aviso(f"não foi possível tocar o som: {erro}")
Não esconda problemas em um alarme que representa condição crítica. Nesse caso, acione outro canal.
Teste
Teste com o arquivo ausente, WAV inválido, saída de áudio desativada, dispositivo trocado, sessão remota, serviço, várias notificações, shutdown durante loop, usuário com sons do sistema personalizados e reprodução em máquina virtual.
Testes unitários podem substituir a chamada por um mock, mas mantenha testes manuais no Windows real.
Arquitetura recomendada
Crie uma interface pequena, como notificar(evento), e deixe um backend Windows usar winsound. Outros sistemas podem usar outro backend ou apenas log visual. Isso evita espalhar imports condicionais por toda a aplicação.
Centralize prioridades, cooldown, repetição e cancelamento.
Erros comuns
Os erros mais frequentes são presumir suporte a qualquer formato, bloquear a GUI com reprodução síncrona, iniciar SND_LOOP sem cancelamento, depender apenas de áudio, usar caminho não confiável, ignorar preferências do usuário e esperar que serviços reproduzam som na sessão correta.
Conclusão
winsound resolve notificações e efeitos simples no Windows com poucas linhas. Use MessageBeep() para eventos do sistema, PlaySound() para WAV e aliases e Beep() para tons básicos.
Mantenha fallback visual, respeite acessibilidade, controle loops e não trate essa API como motor multimídia. Consulte a documentação oficial de winsound e veja msvcrt no Python para outras integrações com Windows.
