SAM Cloud M3U Crawler

Crawler asíncrono en Python para consultar enlaces de escucha de SAM Broadcaster Cloud, seguir redirecciones, detectar icy-name y generar una lista M3U con la URL final redirigida.

Important

Utiliza este proyecto únicamente sobre rangos y servicios para los que tengas autorización. La enumeración masiva de SID o una concurrencia extrema puede incumplir condiciones del proveedor o degradar el servicio. El proyecto usa valores prudentes por defecto y bloquea configuraciones agresivas sin una confirmación explícita.

Funciones

• Rango SID configurable, incluido 0-999999.
• Hasta 2048 tareas/conexiones configurables como techo técnico.
• Límites separados de concurrencia total, por host y peticiones por segundo.
• Seguimiento de redirecciones HTTP 301, 302, 303, 307 y 308.
• La M3U contiene la URL final, no el enlace intermedio de la API.
• Detección de icy-name, ice-name, x-audiocast-name y descripción ICY.
• Detección básica de M3U/PLS devueltos como cuerpo y extracción del primer stream.
• Reintentos, timeout, checkpoint, reanudación y base SQLite.
• Exportación M3U y JSONL.
• CI y ejecución manual/programada mediante GitHub Actions.

Instalación

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\\Scripts\\activate
python -m pip install -e ".[dev]"

Ejemplo prudente

samcloud-m3u \
  --start 0 \
  --end 9999 \
  --concurrency 32 \
  --per-host 16 \
  --max-rps 8

Archivos generados:

• output/samcloud.m3u
• output/stations.jsonl
• data/stations.sqlite3
• data/next_sid.txt

Rango completo

El rango completo se expresa así, pero debería dividirse en lotes y ejecutarse solo con permiso del proveedor:

samcloud-m3u --start 0 --end 999999 --resume

Techo de 2048 conexiones

El programa admite --concurrency 2048, pero las configuraciones de alta carga están bloqueadas salvo confirmación expresa. Incluso con autorización, empieza con cifras bajas y mide la respuesta del servidor.

samcloud-m3u \
  --start 0 \
  --end 999999 \
  --concurrency 2048 \
  --per-host 2048 \
  --max-rps 2048 \
  --acknowledge-load I_HAVE_PERMISSION

No se recomienda esta configuración en un runner compartido ni contra un único host público. El límite max-rps suele ser más importante que el número de tareas.

Reanudación

samcloud-m3u --start 0 --end 999999 --resume

El checkpoint contiene el siguiente SID pendiente. SQLite conserva y actualiza resultados anteriores; la M3U se regenera ordenada y sin duplicados por SID.

Formato M3U

#EXTM3U
#EXTINF:-1 sid="123" group-title="SAM Cloud" content-type="audio/mpeg",Nombre detectado
https://servidor-final.example/live.mp3

GitHub Actions

• CI: instala, ejecuta Ruff y las pruebas.
• Crawl and build M3U: ejecución manual con rango y límites configurables.
• Programación semanal: usa por defecto 0-9999, 32 tareas, 16 conexiones por host y 8 peticiones/s.
• Para cambiar el rango programado, crea las variables de repositorio SAMCLOUD_START y SAMCLOUD_END.
• Los resultados se suben como artifact durante 30 días.
• En una ejecución manual, publish=true publica output/ y el checkpoint en la rama predeterminada.

GitHub advierte que los workflows programados pueden retrasarse en periodos de carga y que los runners alojados tienen un máximo de seis horas por job. Por eso conviene usar lotes pequeños y programar fuera del minuto 0.

Limitaciones

• Algunos servidores antiguos responden con una línea de estado no estándar ICY 200 OK; aiohttp puede rechazar esos endpoints. Los servidores modernos suelen devolver HTTP normal con cabeceras icy-*.
• Cerrar una respuesta de audio tras leer sus cabeceras minimiza ancho de banda, pero sigue contando como una conexión al servicio.
• Una URL que responde correctamente no garantiza que la emisora esté permanentemente activa.
• El proyecto no intenta saltarse autenticación, CAPTCHA, bloqueos, cuotas ni controles de acceso.

Referencias

• Documentación de clientes y conectores aiohttp: https://docs.aiohttp.org/en/stable/client.html
• Límites de GitHub Actions: https://docs.github.com/actions/reference/limits
• Eventos programados de Actions: https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule
• Guías SAM Broadcaster Cloud: https://support.spacial.com/hc/en-us/sections/206508527-User-Guides

Licencia

MIT. El proyecto no está afiliado a Spacial, Triton Digital ni GitHub.

Publicar como repositorio nuevo

Con GitHub CLI autenticado:

./scripts/publish.sh samcloud-m3u-crawler public

En PowerShell:

.\scripts\publish.ps1 -RepositoryName samcloud-m3u-crawler -Visibility public