st.image, st.audio, st.video y st.pdf para contenido multimedia

st.image: mostrar imágenes

La función st.image es el componente principal para mostrar imágenes en Streamlit. Acepta múltiples fuentes de datos: URLs, rutas locales, arrays NumPy, objetos PIL y bytes en bruto. Esta versatilidad permite desde mostrar logotipos descargados de Internet hasta visualizar resultados de procesamiento de imagen con bibliotecas de ciencia de datos.

import streamlit as st
import numpy as np
from PIL import Image

# Desde URL
st.image(
    "https://streamlit.io/images/brand/streamlit-logo-secondary-colormark-darktext.png",
    caption="Logo de Streamlit",
    width=300
)

# Desde ruta local
st.image("assets/foto_producto.jpg", use_container_width=True)

El parámetro use_container_width=True hace que la imagen se escale para ocupar todo el ancho del contenedor padre, lo que resulta fundamental para crear interfaces responsive que se adapten a distintos tamaños de pantalla.

flowchart TD
    A[Multimedia en app] --> B{"Tipo de medio?"}
    B -->|Imagen| C[st.image url path PIL numpy bytes]
    B -->|Audio| D[st.audio bytes path URL]
    B -->|Video| E[st.video YouTube path bytes]
    B -->|PDF| F[st.pdf documento]
    C --> G[caption width use_container_width]
    D --> H[start_time format mp3]
    E --> I[autoplay loop muted]
    F --> J[Render embedded viewer]
    G --> K[Galeria responsive]
    H --> L[Reproductor en página]
    I --> M[Tutorial demo embed]
    J --> N[Documentación descargable]

Cuando se trabaja con datos científicos, es habitual generar imágenes directamente desde arrays NumPy. Streamlit puede renderizar arrays de enteros (rango 0-255) y de punto flotante (rango 0.0-1.0):

# Array NumPy (escala de grises o RGB)
imagen_ruido = np.random.randint(0, 256, (200, 300, 3), dtype=np.uint8)
st.image(imagen_ruido, caption="Imagen generada con NumPy")

# Objeto PIL
img_pil = Image.new("RGB", (300, 200), color=(255, 75, 75))
st.image(img_pil, caption="Imagen PIL roja")

Para mostrar múltiples imágenes en formato galería, la combinación con st.columns permite crear mosaicos horizontales:

imagenes = [
    "https://picsum.photos/200/150?random=1",
    "https://picsum.photos/200/150?random=2",
    "https://picsum.photos/200/150?random=3"
]
col1, col2, col3 = st.columns(3)
for col, url in zip([col1, col2, col3], imagenes):
    col.image(url, use_container_width=True)

Parámetros clamp y output_format

El parámetro clamp resulta especialmente útil cuando se trabaja con arrays de punto flotante que pueden contener valores fuera del rango esperado. Al activar clamp=True, los valores se recortan automáticamente al rango [0, 1] para evitar errores de renderizado:

import streamlit as st
import numpy as np

# clamp: limitar valores flotantes al rango [0, 1]
img_float = np.random.rand(100, 100, 3)
st.image(img_float, clamp=True, caption="Array flotante clamped a [0,1]")

# output_format: forzar JPEG (más comprimido) o PNG (sin pérdida)
st.image("foto.png", output_format="JPEG", caption="Servida como JPEG")

El parámetro output_format permite elegir entre JPEG (menor peso, ideal para fotografías) y PNG (sin pérdida, mejor para diagramas y capturas con texto). Cuando no se específica, Streamlit elige automáticamente según el tipo de imagen original.

st.audio: reproducir audio

st.audio incrusta un reproductor de audio HTML5 en la aplicación. Soporta archivos locales, URLs, objetos de bytes y datos generados programáticamente. Es la forma directa de ofrecer reproducción de audio sin depender de servicios externos.

import streamlit as st

# Desde archivo local
st.audio("musica.mp3", format="audio/mpeg")

# Con tiempo de inicio
st.audio("podcast.mp3", start_time=120)  # Empezar en el minuto 2

En el ámbito de la ciencia de datos y el procesamiento de señales, resulta frecuente generar audio de forma programática. El siguiente ejemplo crea un tono sinusoidal de 440 Hz (nota La4) y lo envuelve en un contenedor WAV para que el reproductor del navegador lo interprete correctamente:

import streamlit as st
import numpy as np
import io
import wave

# Generar tono de 440Hz (La4)
sample_rate = 44100
duration = 2.0
frecuencia = 440.0
t = np.linspace(0, duration, int(sample_rate * duration))
audio_data = (np.sin(2 * np.pi * frecuencia * t) * 32767).astype(np.int16)

buffer = io.BytesIO()
with wave.open(buffer, "wb") as wf:
    wf.setnchannels(1)
    wf.setsampwidth(2)
    wf.setframerate(sample_rate)
    wf.writeframes(audio_data.tobytes())

st.audio(buffer.getvalue(), format="audio/wav")
st.caption("Tono La4 (440 Hz) generado con NumPy")

Este patrón es extensible a cualquier algoritmo de síntesis de audio: basta con generar el array NumPy con la forma de onda deseada y escribirlo en un buffer WAV o MP3.

st.video: vídeos locales y YouTube

st.video permite incrustar vídeos locales y de YouTube directamente en la aplicación. El componente renderiza un reproductor HTML5 completo con controles de reproducción, volumen y pantalla completa.

import streamlit as st

# Vídeo local
st.video("demo_app.mp4")

# YouTube (URL completa o ID del vídeo)
st.video("https://www.youtube.com/watch?v=B2iAodr0fOo")

# Con tiempo de inicio (segundos)
st.video("tutorial.mp4", start_time=30)

# Con subtítulos
st.video("presentacion.mp4", subtitles="subtitulos.vtt")

El parámetro subtitles acepta archivos en formato VTT (WebVTT), que es el estándar para subtítulos en HTML5. Esto resulta útil para vídeos educativos o presentaciones que requieren accesibilidad.

Cuando se utiliza una URL de YouTube, Streamlit incrusta un iframe del reproductor de YouTube, aprovechando su CDN para la transmisión del vídeo. Para vídeos locales, el archivo se sirve desde el servidor de Streamlit, lo que implica considerar el tamaño del archivo y el ancho de banda disponible.

st.pdf: mostrar documentos PDF

st.pdf (disponible desde Streamlit 1.38) incrusta un visor de PDF directamente en la aplicación, permitiendo al usuario navegar entre páginas, hacer zoom y desplazarse por el documento sin abandonar la interfaz.

import streamlit as st

# Desde bytes
with open("informe_ventas.pdf", "rb") as f:
    contenido_pdf = f.read()

st.pdf(contenido_pdf)

# Con altura personalizada
st.pdf(contenido_pdf, height=600)

La combinación de st.pdf con st.file_uploader crea un flujo completo de carga y previsualización de documentos:

archivo = st.file_uploader("Sube un PDF", type="pdf")
if archivo:
    st.pdf(archivo.read())

A diferencia de las soluciones basadas en st.download_button que fuerzan la descarga, st.pdf muestra el documento dentro de la propia aplicación, lo que mejora la experiencia del usuario al permitir la consulta inmediata sin cambiar de contexto.

Ejemplo integrado: galería de productos con multimedia

El siguiente ejemplo combina st.image, st.metric, st.columns y st.container para construir un catálogo visual de productos. Este patrón es representativo de las aplicaciones de tipo dashboard donde cada registro incluye contenido multimedia y datos estructurados:

import streamlit as st

productos = [
    {"nombre": "Laptop Pro 14", "precio": 1299.99, "imagen": "https://picsum.photos/300/200?random=10"},
    {"nombre": "Monitor 27\"", "precio": 349.50, "imagen": "https://picsum.photos/300/200?random=11"},
    {"nombre": "Teclado mecánico", "precio": 129.00, "imagen": "https://picsum.photos/300/200?random=12"},
]

st.title("Catálogo de productos")

for i, p in enumerate(productos):
    with st.container(border=True):
        col_img, col_info = st.columns([1, 2])
        with col_img:
            st.image(p["imagen"], use_container_width=True)
        with col_info:
            st.subheader(p["nombre"])
            st.metric("Precio", f"€ {p['precio']:.2f}")
            if st.button(f"Añadir al carrito", key=f"btn_{i}", type="primary"):
                st.success(f"'{p['nombre']}' añadido al carrito.")

Cada producto se envuelve en un st.container(border=True) que delimita visualmente la ficha, mientras que st.columns([1, 2]) establece una proporción de un tercio para la imagen y dos tercios para la información textual. El parámetro key en el botón garantiza que Streamlit pueda distinguir cada instancia dentro del bucle.