El módulo winsound ofrece acceso sencillo a funciones de audio de Windows. Puede reproducir sonidos del sistema, archivos WAV, aliases registrados, loops asíncronos y tonos básicos generados mediante la interfaz del speaker. Resulta útil para notificaciones locales, herramientas administrativas, prototipos, programas educativos y pequeñas utilidades que necesitan feedback audible sin instalar una biblioteca externa.
No es un motor de audio completo. No ofrece mezcla multicanal, reproducción general de MP3, streaming, edición, volumen preciso por sonido ni síntesis de baja latencia. Además, solo está disponible en Windows. Para aplicaciones portables o multimedia avanzada, utiliza una biblioteca dedicada.
Disponibilidad
Protege el import cuando el proyecto también deba funcionar en Linux o macOS.
import sys
if sys.platform == "win32":
import winsound
else:
winsound = None
Una aplicación puede ofrecer una notificación visual cuando el audio no esté disponible. Esto también mejora la accesibilidad y evita que el sonido sea la única indicación de un error.
El primer beep
Beep(frequency, duration) produce un tono con frecuencia en hertz y duración en milisegundos.
import winsound
winsound.Beep(880, 200)
Los límites aceptados dependen de la implementación de Windows. Valores inválidos generan un error. La llamada bloquea mientras se reproduce el tono, así que evita duraciones largas en una GUI o dentro de un loop cerrado.
Crea una secuencia de tonos
Una melodía simple puede representarse mediante pares de frecuencia y duración.
import winsound
notas = [
(523, 150),
(659, 150),
(784, 250),
]
for frecuencia, duracion in notas:
winsound.Beep(frecuencia, duracion)
Es apropiado para demostraciones y feedback básico, no para música profesional. El timing, el timbre y la polifonía son limitados.
Sonidos del sistema con MessageBeep
MessageBeep() reproduce un sonido asociado a un evento de Windows. Constantes como MB_ICONASTERISK, MB_ICONEXCLAMATION, MB_ICONHAND, MB_ICONQUESTION y MB_OK identifican categorías conocidas.
import winsound
winsound.MessageBeep(winsound.MB_ICONEXCLAMATION)
El usuario puede haber personalizado o desactivado esos sonidos. No supongas que un evento siempre produce el mismo audio.
PlaySound para archivos y aliases
PlaySound(sound, flags) es la entrada más flexible. El primer argumento identifica un archivo, alias o datos en memoria, mientras las flags indican cómo interpretarlo.
import winsound
winsound.PlaySound(
r"C:\Windows\Media\notify.wav",
winsound.SND_FILENAME,
)
Usa una raw string para rutas Windows o construye la ruta con pathlib.Path. Comprueba la existencia cuando la aplicación necesite un diagnóstico específico para un archivo ausente.
Archivos WAV
La API está orientada a sonidos compatibles con el mecanismo tradicional de Windows, especialmente WAV. No esperes que un archivo funcione solo porque un reproductor de escritorio puede abrirlo. El formato, codec, canales y parámetros de sample pueden influir.
Para MP3, OGG, FLAC, streaming o reproducción avanzada, elige una biblioteca de audio apropiada.
Aliases del sistema
Con SND_ALIAS, el primer argumento es el nombre de un evento sonoro registrado en Windows.
winsound.PlaySound(
"SystemAsterisk",
winsound.SND_ALIAS,
)
Los aliases pueden variar según la versión, configuración e idioma de Windows. Incluye fallback y evita nombres no documentados.
Reproducción asíncrona
SND_ASYNC inicia la reproducción y vuelve inmediatamente.
winsound.PlaySound(
"alerta.wav",
winsound.SND_FILENAME | winsound.SND_ASYNC,
)
print("La aplicación continúa")
La reproducción usa estado compartido del proceso y del sistema. Una llamada posterior puede reemplazar o interrumpir el sonido anterior según las flags y el entorno.
Repite con SND_LOOP
SND_LOOP repite el sonido. Combínalo con reproducción asíncrona para que el programa continúe y pueda detener el loop más adelante.
winsound.PlaySound(
"alarma.wav",
winsound.SND_FILENAME | winsound.SND_ASYNC | winsound.SND_LOOP,
)
Un loop sin ruta de parada crea una mala experiencia. Ofrece cancelación y detén el audio durante shutdown, excepciones o cambios de pantalla.
Detén un sonido
Una llamada con None detiene la reproducción controlada por PlaySound().
winsound.PlaySound(None, 0)
Usa un bloque finally cuando el sonido sea temporal.
try:
iniciar_alarma()
ejecutar_tarea()
finally:
winsound.PlaySound(None, 0)
No interrumpas un sonido activo
SND_NOSTOP solicita que la llamada falle en lugar de sustituir un sonido que ya se está reproduciendo. Puede servir cuando una notificación secundaria no debe interrumpir una alarma importante.
Trata el fallo como estado normal y no como error fatal.
Controla el fallback
SND_NODEFAULT impide que Windows use un sonido predeterminado cuando no encuentra el solicitado. Sin esta flag, el usuario puede escuchar algo distinto de lo previsto.
Elige conscientemente entre silencio, fallback propio y sonido estándar del sistema.
Datos en memoria
SND_MEMORY permite proporcionar bytes WAV desde memoria.
from pathlib import Path
import winsound
datos = Path("alerta.wav").read_bytes()
winsound.PlaySound(datos, winsound.SND_MEMORY)
Este modo no es compatible con todas las opciones asíncronas. Además mantiene los bytes en memoria mientras son necesarios. Limita tamaño y valida archivos no confiables antes de cargarlos.
Aplicaciones gráficas
Las llamadas síncronas bloquean la thread actual. En una GUI pueden congelar botones, entrada y rendering. Usa reproducción asíncrona o envía una operación corta a un worker controlado, manteniendo cancelación.
No crees una thread ilimitada por cada notificación. Un gestor central puede serializar sonidos, aplicar prioridades y limpiar loops.
Servicios y sesiones no interactivas
Un servicio de Windows, tarea programada, proceso remoto o sesión de background puede no tener un destino de audio interactivo. El usuario esperado quizá nunca escuche el sonido.
Los alertas operativos también deben usar logs, métricas, e-mail o un servicio de notificaciones. El audio local no es un canal fiable de monitorización.
Volumen y preferencias
winsound no expone un control general de volumen por aplicación. El resultado depende del mixer de Windows, dispositivo activo, mute, políticas y preferencias del usuario.
Respeta una opción para desactivar sonidos. No aumentes repetición o duración para compensar silencio.
Accesibilidad
El feedback audible debe estar acompañado por texto, icono, estado visual, vibración u otro canal apropiado. Algunos usuarios no oyen el sonido, trabajan en un entorno compartido o utilizan tecnologías asistivas.
Evita alertas repentinos, muy fuertes o excesivamente largos. Permite probar y configurar el comportamiento.
Seguridad de rutas
No construyas una ruta de audio directamente con entrada no confiable. Restringe assets a un directorio conocido y verifica la ruta resuelta.
from pathlib import Path
base = Path("sonidos").resolve()
candidato = (base / nombre_archivo).resolve()
if base not in candidato.parents:
raise ValueError("archivo fuera del directorio permitido")
Esto ayuda contra path traversal, aunque permisos y enlaces simbólicos también requieren atención.
Errores y fallbacks
Los fallos suelen aparecer como RuntimeError. Captura la operación de audio, registra contexto útil y continúa solo cuando el sonido sea opcional.
try:
winsound.PlaySound("alerta.wav", winsound.SND_FILENAME)
except RuntimeError as error:
registrar_aviso(f"no se pudo reproducir el sonido: {error}")
No silencies el fallo de una alarma que representa una condición crítica. Activa otro canal.
Pruebas
Prueba archivo ausente, WAV inválido, salida silenciada, cambio de dispositivo, sesión remota, servicio, varias notificaciones, shutdown durante un loop, sonidos personalizados y máquinas virtuales.
Los tests unitarios pueden reemplazar la llamada por un mock, pero conserva pruebas manuales en Windows real.
Arquitectura recomendada
Crea una interfaz pequeña como notificar(evento) y permite que un backend Windows use winsound. Otros sistemas pueden usar otro backend o solo feedback visual. Así evitas imports condicionales por toda la aplicación.
Centraliza prioridades, cooldown, repetición y cancelación.
Errores comunes
Los fallos frecuentes son asumir soporte para cualquier formato, bloquear la GUI con reproducción síncrona, iniciar SND_LOOP sin cancelación, depender únicamente de audio, aceptar una ruta no confiable, ignorar preferencias y esperar que un servicio reproduzca sonido en la sesión correcta.
Conclusión
winsound resuelve notificaciones y efectos simples en Windows con muy poco código. Usa MessageBeep() para eventos del sistema, PlaySound() para WAV y aliases y Beep() para tonos básicos.
Ofrece fallback visual, respeta accesibilidad, controla loops y no trates la API como motor multimedia. Consulta la documentación oficial de winsound y lee msvcrt en Python para otras integraciones con Windows.
