Skip to content

README.md

Latest commit

 

History

History
128 lines (92 loc) · 4.72 KB

README.md

File metadata and controls

128 lines (92 loc) · 4.72 KB
Raw

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

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