Metadata-Version: 2.4
Name: basskit
Version: 0.8.12
Summary: Audio, vídeo y conversión multimedia para Python: BASS (Un4seen) y FFmpeg 8.1 - Solo Windows 64 bits
Author: basskit contributors
License-Expression: LicenseRef-Basskit-Bundle
Keywords: bass,audio,sound,music,streaming,un4seen,windows,ffmpeg,video,multimedia,transcoding
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Video :: Conversion
Classifier: Topic :: Multimedia :: Video :: Display
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Provides-Extra: dev
Requires-Dist: pytest>=9; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pcpp==1.30; extra == "dev"
Requires-Dist: pycparser==3.0; extra == "dev"
Requires-Dist: libclang==18.1.1; extra == "dev"
Dynamic: license-file

# basskit 0.8.4

Biblioteca Python de **audio, vídeo y conversión multimedia** para
**Windows AMD64**: BASS (Un4seen) con sus 32 módulos y **FFmpeg 8.1.2**
completo (avcodec, avformat, avutil, avfilter, swscale, swresample y
avdevice) en una sola rueda. Mantiene la API en español; requiere Python
3.13 o posterior y se valida con 3.13, 3.13 free-threaded (sin GIL), 3.15
candidato y 3.15 free-threaded (sin GIL). Python 3.14 está descartado.

## Instalación

```powershell
py -3.13 -m pip install .\dist\basskit-0.8.4-py3-none-win_amd64.whl
py -3.13 -m basskit --json
py -3.13 -m basskit --integridad
py -3.13 -m basskit --multimedia --inspeccionar video.mp4
```

Para desarrollo: `python -m pip install -e ".[dev]"`. La rueda contiene 41
DLL AMD64 y dos ejecutables auxiliares; por ello no usa la etiqueta
universal `any`. No es un paquete para Linux, macOS, Windows x86 ni ARM64.

## Vídeo y conversión

```python
from basskit import multimedia as mm

info = mm.inspeccionar("entrada.mkv")
print(info.duracion, [(p.tipo, p.codec, p.ancho, p.frecuencia) for p in info.pistas])

mm.convertir("entrada.mkv", "salida.mp4",
             video=mm.ConfigVideo(ancho=1280, opciones={"preset": "fast", "crf": 23}),
             progreso=lambda p: print(p.fraccion))
mm.remux("entrada.mkv", "copia.mp4")                         # sin recodificar
mm.extraer_audio("salida.mp4", "audio.m4a")
mm.convertir("salida.mp4", "corte.mp4", inicio=30, duracion=10)
mm.miniatura("salida.mp4", "portada.jpg", representativa=True)
mm.agregar_subtitulos("salida.mp4", "subs.srt", "con_subs.mp4", idioma="spa")

with mm.Entrada("salida.mp4") as e:
    for f in e.fotogramas("video", desde=12.0):              # seek exacto
        with f:
            datos, ancho, alto, stride = mm.a_rgb(f)
            break
```

Todo usa las DLL mediante ctypes, dentro del proceso: no hace falta
`ffmpeg.exe` en el PATH. La [guía multimedia](docs/multimedia/README.md)
cubre inspección, lectura, codificación, conversión, filtros, imágenes y
color, subtítulos, reproducción A/V, dispositivos, streaming, hardware,
rendimiento y errores.

Reproducción: `mm.ReproductorMultimedia` decodifica y sincroniza con el
audio de BASS y entrega fotogramas RGB/BGRA para cualquier GUI, con
velocidad variable y el subtítulo activo en cada instante; ejemplos para
[wxPython](examples/reproductor_video_wx.py) y
[pygame](examples/reproductor_video_pygame.py). No depende de ninguna
biblioteca gráfica.

## Reproductor y grabador completos

```python
rep = mm.ReproductorMultimedia('pelicula.mkv', formato_video='bgra', ancho=1280,
                               subtitulos='auto')
rep.reproducir()
rep.cambiar_pista_audio(2)                 # en caliente, sin perder la posición
rep.ir_a_capitulo(3)
rep.ajustar_video(desentrelazar='auto', brillo=0.05, rotacion=90)
rep.ecualizar([6, 4, 2, 0, 0, -2, 0, 3, 5, 6])
rep.velocidad = 1.5                        # el tono no cambia
rep.fijar_bucle(120, 180)
rep.captura('foto.png')
rep.iniciar_grabacion('copia.mkv')         # graba lo que suena, sin recodificar
fotograma = rep.fotograma_actual()         # listo para wx.Bitmap.FromBuffer

g = mm.Grabadora('clase.mp4', video=mm.pantalla(fps=30),
                 audio=[mm.microfono(), mm.audio_sistema()],
                 superpuesta=mm.camara(), marca_tiempo=True, segmentar=600)
g.iniciar()
```

El área de vídeo es una ventana normal de wx que usted pinta: sirve igual
para la ventana, para pantalla completa y para poner el vídeo **de fondo del
escritorio con los iconos encima** (`basskit.herramientas.escritorio`).
Listas M3U, PLS, XSPF y ASX con `mm.leer_lista`.

Audio comprimido al amplificador sin decodificar
(`mm.reproducir_passthrough`, AC3/DTS/E-AC3 por S/PDIF o HDMI), envío a un
Chromecast (`basskit.red.cast`, con descubrimiento mDNS y servidor propio) y
extensiones del usuario en Python (`basskit.extensiones`).

DVD y Blu-ray con libdvdnav y libbluray: `mm.listar_titulos_dvd('D:/')`,
`mm.reproducir_dvd('D:/', titulo=1)`, `mm.reproducir_bluray('E:/')`.
El inventario completo para escribir la interfaz está en
[portar a un reproductor wxPython](docs/reproductor_completo_wxpython.md).

## Medios con contraseña o doble factor

```python
from basskit.red import SesionHTTP

sesion = SesionHTTP.basica('usuario', 'contraseña')        # o .con_token(...)
sesion = SesionHTTP.desde_requests(sesion_web_ya_autenticada)   # flujo 2FA propio

rep = mm.ReproductorMultimedia('https://servidor/pelicula.mkv', sesion=sesion)
reproductor_audio.abrir_url(url, sesion=sesion,
                            desplazamiento_bytes=sesion.byte_para_segundo(url, 930, duracion))
descargar(url, 'copia.mkv', sesion, progreso=mostrar)
```

Las credenciales viajan como cabeceras HTTP (BASS) u opciones del protocolo
(FFmpeg); cuando la sesión vive en otra biblioteca, basskit la presta por un
proxy local en `127.0.0.1`. `al_reautenticar` renueva la sesión caducada y
reintenta sin cortar la reproducción.

## Novedades de 0.8.8

- La imagen de los `.ts` y de los directos HLS ya no se pierde: el reloj empieza donde empieza el medio
  (`rep.origen`) y la imagen que se adelanta al sonido espera en vez de tirarse.
- `adelanto_directo=` para los directos de televisión: más sonido preparado para aguantar a un servidor lento.

## Novedades de 0.8.7

- **Vídeos sin pausa**: `rep.encadenar(siguiente)` también con imagen; la de la nueva espera en la cola hasta que
  suena su primera muestra (`FotogramaRGB.tramo`). Con `fuente_audio=` encadena fuentes con la imagen y el sonido
  por separado (DASH).
- Buscar en un archivo con imagen y sonido ya no pierde el paquete de audio del punto buscado.

## Novedades de 0.8.4

- **Sin pausas**: `rep.encadenar(siguiente)` pone la siguiente fuente de audio detrás de la actual en la misma
  salida, con las muestras exactas en la juntura (también en AAC: el relleno del último bloque se recorta con la
  duración exacta de la pista) y `al_cruzar` cuando suena.
- **Salidas exclusivas**: `ReproductorMultimedia(salida_audio='wasapi_exclusivo' | 'asio')` (`SalidaWASAPIExclusiva`,
  `SalidaASIO`) o una fábrica propia que cumpla `mm.SalidaAudio`.
- **Fundidos** lineales, de potencia o logarítmicos sin tocar el volumen (`rep.fundir`).
- **Tempo en marcha** sin buscar ni cortar (`tempo_variable=True`, `fijar_tempo`).
- **Canales de salida** elegibles en marcha (`AjustesAudio(canales_salida=)`) y **binaural** con HRIR
  (`AjustesAudio(hrir=, mapa_hrir=)`).
- **CD de audio**: `alto_nivel.DiscoCD` (pistas, CD-Text, ISRC, MusicBrainz, CDDB, UPC) y `LectorPistaCD`, que
  reproduce una pista con FFmpeg.
- **VST**: `alto_nivel.EfectoVST`, con parámetros, programas, bloques de estado, aviso de cambios y traslado a otro
  canal.
- **Metadatos de emisión**: `al_metadatos` avisa del título de las radios ICY y de los Ogg encadenados.
- **Icecast**: `Grabadora(opciones_protocolo=)` y `mm.emitir('icecast://...')`, con las contraseñas tachadas en los
  errores.
- **HDR a SDR** por CPU, OpenCL o Vulkan (`mm.cadena_hdr_a_sdr`, `AjustesVideo.cadena_previa`) y dispositivos de GPU
  en `GrafoFiltros` y en el reproductor (`AjustesVideo.dispositivo_hardware`).
- **Dispositivos de salida** con `tipo`, `driver` y `habilitado`, incluidos los desenchufados.
- Paso atrás de fotograma exacto, estilo de subtítulos libass en vivo, eventos de subtítulos en caché,
  `rotar_grabacion`, disposiciones y `layout` de las pistas, `ajustes_audio_con_info` y `al_cambiar_salida`.
- Fallos de 0.8.3 corregidos: reloj al cambiar de dispositivo, cadena de audio que perdía muestras, rutas con
  apóstrofo en los filtros, literales de constantes y otros. Adaptación en
  [migración a 0.8.4](docs/migracion_0.8.4.md). Sin cambios de DLL.

## Novedades de 0.8.3

- **Imagen y sonido en fuentes separadas.** `ReproductorMultimedia(video, fuente_audio=audio)` reproduce la imagen de
  una fuente y el sonido de otra (DASH de YouTube y similares), sincronizados, con búsqueda en las dos.
  `cambiar_fuente_audio(fuente)` cambia el sonido (otro idioma) sin tocar la imagen ni la posición. Debajo está
  `mm.EntradaCompuesta`, que presenta dos `Entrada` como una. Sin cambios de DLL.

## Novedades de 0.8.2

- **Descubrir extensiones ya no las ejecuta**: `GestorExtensiones.descubrir()` lee `EXTENSION` y los enganches
  del texto con `ast`; el archivo se importa al activarlo. `descubrir(importar=True)` conserva lo anterior.
- `Extension.enganches_declarados` y `GestorExtensiones.recargar(nombre)`. Detalle y adaptación en
  [migración a 0.8.2](docs/migracion_0.8.2.md). Sin cambios de DLL.

## Novedades de 0.8.1

- Filtros que se construyen igual con cualquier configuración regional: con el idioma del proceso en español
  fallaban la grabadora y los ajustes de imagen y sonido del reproductor. Los números van como fracciones.
- El rótulo de la grabadora admite dos puntos, apóstrofos, comas, corchetes, `%` y varias líneas.
- `AjustesVideo(relacion_aspecto='16:9')` ya construye el grafo.

## Novedades de 0.8.0

- Reproductor completo: pistas en caliente, capítulos, filtros de imagen,
  ecualizador y normalización, retardos A/V, bucle A-B, paso a paso,
  captura, grabación de lo reproducido y subtítulos por libass.
- Entrega de fotogramas **sin copias** (`memoryview`) y cola acotada por
  memoria: 4K pasa de 46 a ~100 fps escalando al tamaño del panel.
- Passthrough AC3/DTS/E-AC3, Google Cast y extensiones de aplicación.
- `mm.Grabadora`: pantalla, ventana, cámara, micrófono y audio del sistema,
  mezcla, superposición, hardware con reserva, segmentación y emisión.
- `basskit.red`: sesiones autenticadas (contraseña, testigo, cookies, doble
  factor), proxy local, reanudación por rangos alineada al marco y
  descargas con reanudación y verificación.
- DVD y Blu-ray: títulos, capítulos, ángulos y listas de reproducción.
- `alto_nivel.Reproductor`: `sesion=`, `desplazamiento_bytes=`, tempo con
  tono conservado, ecualizador de diez bandas y `efectos`.

## Novedades de 0.7.0

- `basskit.api`: fachada única y perezosa de las 41 API C (`api.bass`,
  `api.avcodec`, `api.openssl`...). `basskit.multimedia`, `basskit.api` y
  `basskit.alto_nivel` se importan al usarse.
- Reproductor: velocidad 0,25-4 conservando el tono, subtítulos de texto y
  bitmap (`subtitulo_actual()`), pausa sin salto de posición y final
  correcto cuando el audio termina antes que el vídeo.
- Subtítulos bitmap: quemado nativo, exportación a PNG para OCR externo y
  escritura dvdsub/dvbsub desde RGBA.
- `GrafoFiltros` se reconstruye si cambian resolución o formato a mitad de
  flujo; `configurar_log` entrega líneas completas.
- Variante LGPL de la misma compilación FFmpeg aceptada con
  `BASSKIT_FFMPEG_PATH`; se rechaza mezclar conjuntos FFmpeg en un proceso.
- Estructuras de `hwcontext_cuda.h` y `hwcontext_opencl.h`.
- `LectorTags` y `Codificador` usan FFmpeg cuando BASS no puede
  (`motor='auto'|'bass'|'ffmpeg'`).
- `tools/bootstrap_sdk.py`: descarga reproducible y verificada de los SDK.
- Pruebas nuevas: 27 de API nativa FFmpeg con oráculos independientes;
  HLS, HTTPS, RTMP y RIST locales; errores TLS de OpenSSL; BASSMIDI con
  SoundFont sintética; plugin VST 2 propio; WASAPI en el dispositivo real
  (silencio); captura gdigrab de una ventana propia; OptimFROG en casos
  límite. Detalle en [migración a 0.7.0](docs/migracion_0.7.0.md).

## Audio con BASS

```python
from basskit.alto_nivel import inicializar, liberar, Codificador, FlujoPCM

inicializar(0)  # Decodificación sin tarjeta de sonido
try:
    Codificador().convertir("entrada.wav", "salida.flac", opciones="-5")
    with FlujoPCM("salida.flac") as flujo:
        print(flujo.frecuencia, flujo.canales)
        for bloque in flujo:
            # bytes PCM float32, canales intercalados, bloques acotados
            pass
finally:
    liberar()
```

`FlujoPCM` también acepta `bytes`. `motor="ffmpeg"` permite enumerar y
elegir pistas compatibles; `motor="dts"` selecciona el decodificador DTS.
Se incluye **BASS 2.4.18.23 del canal oficial de desarrollo**, seleccionado
tras reproducir fallos HTTP con la versión estable 2.4.18.3.

## Capacidades

- 5627 funciones nativas tipadas en 41 módulos: 446 de BASS y addons y
  5181 de las DLL auxiliares (1033 FFmpeg, 4129 OpenSSL, 19 OptimFROG).
  Tipos y tamaños contrastados con MSVC. Inventarios en
  [auditoría](docs/auditoria_sdk.md) y [matriz de evidencia](docs/matriz_evidencia.md).
- FFmpeg: 235 codificadores, 550 decodificadores, 364 demuxers, 184
  muxers, 566 filtros, 40 protocolos de entrada, dshow/gdigrab/lavfi, y
  D3D11VA, DXVA2, D3D12VA, CUDA, OpenCL, Vulkan, NVENC, AMF, QSV y Media
  Foundation según el hardware ([matriz de capacidades](docs/multimedia/matriz_capacidades.md)).
- Reproductor A/V con pistas, capítulos, filtros, ecualizador, subtítulos,
  bucles, captura y grabación; grabadora de pantalla, cámara, micrófono y
  audio del sistema con emisión en directo; sesiones HTTP autenticadas y
  descargas reanudables; DVD y Blu-ray.
- Desde 0.8.4: reproducción sin pausas, fundidos, tempo en marcha, binaural con HRIR, salidas
  WASAPI exclusiva y ASIO en el reproductor, metadatos de emisión (ICY y Ogg encadenado), emisión
  a Icecast y HDR a SDR por CPU, OpenCL o Vulkan.
- BASS: reproducción de archivos y URL, muestras, MOD, audio 3D, MIDI,
  grabación, WASAPI, ASIO, VST2 (`EfectoVST`), CD (`DiscoCD`, `LectorPistaCD`), HTTP/HLS, efectos (`CadenaEfectos`),
  análisis (`Analizador`: FFT, RMS, BPM, LUFS, true peak), codificación
  MP3/FLAC/Vorbis/Opus y mezcla.
- API independientes de OpenSSL (TLS, certificados, criptografía) y
  OptimFROG.

## Acceso nativo

```python
from basskit import api

print(hex(api.bass.BASS_GetVersion()), api.avutil.avutil_version())
avfilter = api.obtener("avfilter")          # alias o nombre exacto: "avfilter-11"
print(len(dir(avfilter)), api.listar())
```

Las funciones conservan la semántica C: compruebe retornos y mantenga
vivos buffers y callbacks mientras los use la biblioteca. Los objetos de
`basskit.multimedia` exponen sus punteros (`ctx`, `ptr`) para mezclar ambos
niveles. `BASSKIT_DLL_PATH` permite otro directorio de DLL y
`BASSKIT_FFMPEG_PATH` otra carpeta FFmpeg (la variante LGPL) antes de la
primera carga; las API auxiliares verifican el SHA-256 de cada binario.

## Documentación y validación

- [Índice de toda la documentación](docs/README.md) y [manual completo](docs/manual_completo.md).
- [Reproductor y grabador completos, para portar a wxPython](docs/reproductor_completo_wxpython.md)
  y migración [a 0.8.4](docs/migracion_0.8.4.md), [a 0.8.2](docs/migracion_0.8.2.md) y
  [a 0.8.0](docs/migracion_0.8.0.md).
- [Guía multimedia](docs/multimedia/README.md), [migración a 0.7.0](docs/migracion_0.7.0.md)
  y [desde 0.5.0](docs/migracion_0.6.0.md).
- [Referencia de las 41 DLL](docs/dll/README.md) y [API auxiliares](docs/auxiliares/README.md).
- [Validación 0.8.2](docs/validacion_0.8.2.json) e [historial](CHANGELOG.md).
- [Licencias](THIRD_PARTY_NOTICES.md): el MIT del wrapper no se extiende a
  las DLL. **FFmpeg incluido es GPL v3 o posterior**; redistribuir exige
  cumplirla (código fuente correspondiente). La variante LGPL de la misma
  compilación es la alternativa documentada.

```powershell
python -m pytest
python tools/matriz_evidencia.py build\traza_llamadas.json build\junit.xml
python tools/construir_distribucion.py
```

La validación automatizada usa medios sintéticos, dispositivo BASS 0 o la
salida predeterminada a volumen 0, la GPU del equipo cuando existe y
servidores locales en 127.0.0.1 (HLS, HTTPS, RTMP, RIST). No certifica
cámaras, micrófonos, captura del escritorio, ASIO, WASAPI exclusivo,
unidades CD, instrumentos VST de terceros, SRT (su caller no emite el
handshake en este equipo) ni servidores remotos; la matriz de capacidades
indica qué se ejecutó y qué depende de recursos externos.
