Escribir Etiquetas de Audio con SDK de Media Blocks¶

Tabla de Contenidos¶

Escribir Etiquetas de Audio con SDK de Media Blocks
Tabla de Contenidos
Resumen
Características Principales
Formatos de Audio Soportados
Prerrequisitos
MediaFileTags: La Interfaz Unificada
Ejemplos de Código por Formato
Ejemplo Completo de Grabación de Audio
Escenarios Avanzados de Etiquetas
Mejores Prácticas
Solución de Problemas
- Problemas y Soluciones Comunes
- Depuración de Escritura de Etiquetas
Especificaciones de Formato de Etiquetas

Resumen¶

El SDK de VisioForge Media Blocks proporciona soporte completo para escribir etiquetas de metadatos de audio en archivos de salida en todos los formatos de audio principales. Ya sea que esté creando una aplicación de producción musical, un grabador de podcasts o un sistema de gestión de contenido de audio, puede incrustar fácilmente metadatos ricos en sus archivos de audio utilizando una interfaz de programación unificada.

Esta guía demuestra cómo agregar etiquetas de metadatos como artista, álbum, título, año, género y más a archivos MP3, OGG Vorbis, M4A y WMV/WMA utilizando mecanismos de etiquetado apropiados para el formato mientras se mantiene el cumplimiento de estándares de la industria.

Características Principales¶

Soporte Universal de Etiquetas: Escribir metadatos en MP3 (ID3), OGG (Comentarios Vorbis), M4A (átomos MP4) y WMV (atributos ASF)
Metadatos Completos: Soporte para 20+ campos de etiquetas incluyendo título, artista, álbum, año, números de pista, letras, y carátula de álbum
Cumplimiento de Estándares: Utiliza mecanismos de etiquetas nativos de contenedor para compatibilidad óptima
API Unificada: Una sola interfaz MediaFileTags funciona en todos los formatos de salida
Calidad Profesional: Escritura de etiquetas de estándares de la industria con codificación y estructura apropiadas
Flexibilidad en Tiempo de Ejecución: Modificar etiquetas antes y durante la ejecución del pipeline

Formatos de Audio Soportados¶

Formato	Contenedor	Sistema de Etiquetas	Estándares
MP3	MPEG-1 Layer 3	ID3v1/ID3v2	ISO/IEC 11172-3, ID3v2.4
OGG Vorbis	OGG	Comentarios Vorbis	Especificación Xiph.Org
M4A	MP4/MPEG-4	átomos de metadatos MP4	Formato de Archivo de Medios Base ISO
WMV/WMA	ASF	atributos de metadatos ASF	Especificación Microsoft ASF

Prerrequisitos¶

SDK de VisioForge Media Blocks .NET
.NET Framework 4.7.2+ o .NET Core 3.1+ o .NET 5+
Comprensión básica de pipelines de procesamiento de audio

using VisioForge.Core.MediaBlocks.Sinks;
using VisioForge.Core.Types;
using VisioForge.Core.Types.X.AudioEncoders;

MediaFileTags: La Interfaz Unificada¶

La clase MediaFileTags proporciona una interfaz unificada para metadatos de audio en todos los formatos soportados. Esta clase contiene todos los campos comunes de metadatos de audio y mapea automáticamente a los formatos de etiquetas apropiados para cada contenedor de salida.

// Crear metadatos de audio completos
var audioTags = new MediaFileTags
{
    // Metadatos básicos
    Title = "Bohemian Rhapsody",
    Performers = new[] { "Queen" },
    Album = "A Night at the Opera",
    Year = 1975,

    // Información de pista
    Track = 11,
    TrackCount = 12,
    Disc = 1,
    DiscCount = 1,

    // Género y categorización
    Genres = new[] { "Progressive Rock", "Opera Rock" },

    // Metadatos extendidos
    Composers = new[] { "Freddie Mercury" },
    Conductor = "Roy Thomas Baker",
    Comment = "Épico de 6 minutos obra maestra",
    Copyright = "© 1975 Queen Productions Ltd.",

    // Metadatos técnicos
    BeatsPerMinute = 72,
    Grouping = "Canciones Épicas",

    // Letras (para formatos soportados)
    Lyrics = @"¿Es esto la vida real?
¿Es esto solo fantasía?
Atrapado en un deslizamiento de tierra
Sin escape de la realidad..."
};

Ejemplos de Código por Formato¶

Salida MP3 con Etiquetas ID3¶

Los archivos MP3 usan etiquetas ID3 (tanto v1 como v2) para metadatos. El SDK utiliza el elemento id3mux de GStreamer para escribir etiquetas ID3 compatibles con estándares.

using VisioForge.Core.MediaBlocks.Sinks;
using VisioForge.Core.Types.X.AudioEncoders;

public async Task CreateMP3WithTags()
{
    // Configurar ajustes del codificador MP3
    var mp3Settings = new MP3EncoderSettings
    {
        Bitrate = 320, // Calidad alta 320 kbps
        BitrateMode = MP3BitrateMode.CBR
    };

    // Crear etiquetas de metadatos
    var tags = new MediaFileTags
    {
        Title = "Summer Vibes",
        Performers = new[] { "Indie Artist" },
        Album = "Seasonal Collection",
        Year = 2025,
        Track = 3,
        TrackCount = 10,
        Genres = new[] { "Indie Pop", "Electronic" },
        Comment = "Grabado en estudio casero",
        Copyright = "© 2025 Independent Label"
    };

    // Crear bloque de salida MP3 con etiquetas
    var mp3Output = new MP3OutputBlock("output.mp3", mp3Settings, tags);

    // Alternativa: Establecer etiquetas después de la creación
    // var mp3Output = new MP3OutputBlock("output.mp3", mp3Settings);
    // mp3Output.Tags = tags;

    // Construir su pipeline completo
    var pipeline = new MediaBlocksPipeline();

    // Agregar fuente de audio (micrófono, archivo, etc.)
    var audioSource = new AudioCaptureSourceBlock();

    // Conectar y construir pipeline
    pipeline.Connect(audioSource.Output, mp3Output.Input);

    // Iniciar grabación con metadatos
    await pipeline.StartAsync().ConfigureAwait(false);

    // La grabación incluirá etiquetas ID3 en el archivo MP3
    await Task.Delay(30000); // Grabar por 30 segundos

    await pipeline.StopAsync();
}

Salida OGG Vorbis con Comentarios Vorbis¶

Los archivos OGG Vorbis usan Comentarios Vorbis para metadatos, que están incrustados directamente en el stream de audio por el codificador Vorbis.

using VisioForge.Core.MediaBlocks.Sinks;
using VisioForge.Core.Types.X.AudioEncoders;

public async Task CreateOGGWithTags()
{
    // Configurar ajustes del codificador Vorbis
    var vorbisSettings = new VorbisEncoderSettings
    {
        Quality = 0.8f, // Calidad alta (escala 0.0 a 1.0)
        BitrateMode = VorbisBitrateMode.VBR
    };

    // Crear metadatos completos
    var tags = new MediaFileTags
    {
        Title = "Acoustic Session",
        Performers = new[] { "Folk Artist", "Guest Vocalist" },
        AlbumArtists = new[] { "Folk Artist" },
        Album = "Live Sessions",
        Year = 2025,
        Track = 1,
        Genres = new[] { "Folk", "Acoustic" },
        Composers = new[] { "Folk Artist", "Traditional" },
        Comment = "Grabado en vivo en Studio A",

        // Comentarios Vorbis soportan metadatos extensos
        Conductor = "Sound Engineer",
        Grouping = "Live Recordings",
        Lyrics = @"En la tranquilidad de la mañana
Cuando el mundo comienza a despertar
Hay una canción en el silencio..."
    };

    // Crear bloque de salida OGG con comentarios Vorbis
    var oggOutput = new OGGVorbisOutputBlock("output.ogg", vorbisSettings, tags);

    // Construir y ejecutar pipeline
    var pipeline = new MediaBlocksPipeline();
    var audioSource = new AudioFileSourceBlock("input.wav");

    pipeline.Connect(audioSource.Output, oggOutput.Input);

    await pipeline.StartAsync();
    await pipeline.WaitForCompletionAsync();
}

Salida M4A con Metadatos MP4¶

Los archivos M4A usan átomos de metadatos MP4 para almacenar información, compatibles con iTunes y la mayoría de reproductores de medios.

using VisioForge.Core.MediaBlocks.Sinks;
using VisioForge.Core.Types.X.AudioEncoders;

public async Task CreateM4AWithTags()
{
    // Configurar AAC para M4A
    var aacSettings = new AACEncoderSettings
    {
        Bitrate = 256,
        Profile = AACProfile.LC, // Low Complexity para compatibilidad amplia
        Channels = 2
    };

    // Crear metadatos de podcast
    var tags = new MediaFileTags
    {
        Title = "Episode 42: The Future of AI",
        Performers = new[] { "Tech Podcast Host" },
        Album = "Weekly Tech Talk",
        Year = 2025,
        Track = 42,
        Genres = new[] { "Technology", "Podcast" },
        Comment = "Entrevista especial con investigador de IA",
        Copyright = "© 2025 Tech Media Network",

        // Metadatos específicos de podcast
        Subtitle = "Explorando tendencias de inteligencia artificial",
        Grouping = "Season 3"
    };

    // Crear salida M4A con metadatos MP4
    var m4aOutput = new M4AOutputBlock("podcast_episode_42.m4a", tags);

    // Configuración de pipeline para grabación de podcast
    var pipeline = new MediaBlocksPipeline();
    var micSource = new AudioCaptureSourceBlock();

    // Opcional: Agregar procesamiento de audio
    var volumeFilter = new VolumeFilterBlock { Volume = 1.2f };
    var noiseGate = new NoiseGateBlock { Threshold = -40.0f };

    // Conectar cadena de procesamiento
    pipeline.Connect(micSource.Output, volumeFilter.Input);
    pipeline.Connect(volumeFilter.Output, noiseGate.Input);
    pipeline.Connect(noiseGate.Output, m4aOutput.Input);

    await pipeline.StartAsync();
}

Salida WMV/WMA con Metadatos ASF¶

Los formatos Windows Media usan atributos de metadatos ASF (Advanced Systems Format) para almacenar información.

using VisioForge.Core.MediaBlocks.Sinks;
using VisioForge.Core.Types.X.AudioEncoders;
using VisioForge.Core.Types.X.VideoEncoders;
using VisioForge.Core.Types.X.Sinks;

public async Task CreateWMVWithTags()
{
    // Configurar codificadores Windows Media
    var wmaSettings = new WMAEncoderSettings
    {
        Bitrate = 192,
        SampleRate = 44100,
        Channels = 2
    };

    var wmvSettings = new WMVEncoderSettings
    {
        Bitrate = 2000000, // 2 Mbps
        Width = 1920,
        Height = 1080,
        FrameRate = 30
    };

    var asfSettings = new ASFSinkSettings("presentation.wmv");

    // Crear metadatos de presentación
    var tags = new MediaFileTags
    {
        Title = "Q4 Business Review",
        Performers = new[] { "CEO", "CFO", "VP Sales" },
        Album = "Corporate Presentations 2025",
        Year = 2025,
        Genres = new[] { "Business", "Corporate" },
        Comment = "Revisión financiera trimestral y perspectivas",
        Copyright = "© 2025 Business Corp. Confidential",

        // Metadatos corporativos
        Conductor = "Meeting Organizer",
        Grouping = "Executive Presentations"
    };

    // Crear salida WMV con metadatos ASF
    var wmvOutput = new WMVOutputBlock(asfSettings, wmvSettings, wmaSettings, tags);

    // Configuración para video + audio grabación
    var pipeline = new MediaBlocksPipeline();

    // Agregar fuentes de video y audio
    var videoSource = new VideoCaptureSourceBlock();
    var audioSource = new AudioCaptureSourceBlock();

    // Crear pads de entrada para la salida WMV
    var videoPad = wmvOutput.CreateNewInput(MediaBlockPadMediaType.Video);
    var audioPad = wmvOutput.CreateNewInput(MediaBlockPadMediaType.Audio);

    // Conectar fuentes a salida WMV
    pipeline.Connect(videoSource.Output, videoPad);
    pipeline.Connect(audioSource.Output, audioPad);

    await pipeline.StartAsync();
}

Ejemplo Completo de Grabación de Audio¶

Aquí hay un ejemplo completo que demuestra grabación de audio con diferentes formatos de salida y metadatos:

using VisioForge.Core.MediaBlocks;
using VisioForge.Core.MediaBlocks.Sources;
using VisioForge.Core.MediaBlocks.Sinks;
using VisioForge.Core.Types;

public class AudioRecorderWithTags
{
    public async Task RecordAudioWithMetadata()
    {
        // Crear metadatos ricos para la sesión
        var sessionTags = new MediaFileTags
        {
            Title = "Studio Session #1",
            Performers = new[] { "John Doe", "Jane Smith" },
            Album = "Demo Recordings",
            Year = 2025,
            Track = 1,
            Genres = new[] { "Rock", "Alternative" },
            Composers = new[] { "John Doe" },
            Comment = "Primera sesión de grabación de estudio",
            Copyright = "© 2025 Demo Productions",
            BeatsPerMinute = 120,
            Grouping = "Demo Sessions"
        };

        // Crear múltiples formatos de salida con los mismos metadatos
        var outputs = new IMediaBlockSink[]
        {
            // MP3 de alta calidad
            new MP3OutputBlock("session1.mp3", new MP3EncoderSettings 
            { 
                Bitrate = 320, 
                BitrateMode = MP3BitrateMode.CBR 
            }, sessionTags),

            // OGG Vorbis de calidad sin pérdidas
            new OGGVorbisOutputBlock("session1.ogg", new VorbisEncoderSettings 
            { 
                Quality = 1.0f 
            }, sessionTags),

            // M4A profesional
            new M4AOutputBlock("session1.m4a", sessionTags),

            // Formato Windows Media
            new WMVOutputBlock("session1.wma", sessionTags)
        };

        // Configurar pipeline de grabación
        var pipeline = new MediaBlocksPipeline();
        var audioSource = new AudioCaptureSourceBlock();

        // Conectar fuente a todas las salidas (splitter se creará automáticamente)
        foreach (var output in outputs)
        {
            pipeline.Connect(audioSource.Output, output.Input);
        }

        // Iniciar grabación
        Console.WriteLine("Iniciando grabación con metadatos...");
        await pipeline.StartAsync();

        // Grabar por duración especificada
        await Task.Delay(TimeSpan.FromMinutes(3));

        // Detener grabación
        Console.WriteLine("Deteniendo grabación...");
        await pipeline.StopAsync();

        Console.WriteLine("Grabación completa! Archivos creados con metadatos:");
        Console.WriteLine("- session1.mp3 (etiquetas ID3)");
        Console.WriteLine("- session1.ogg (comentarios Vorbis)");
        Console.WriteLine("- session1.m4a (metadatos MP4)");
        Console.WriteLine("- session1.wma (metadatos ASF)");
    }
}

Escenarios Avanzados de Etiquetas¶

Soporte de Carátula de Álbum¶

Agregar carátula de álbum a sus archivos de audio (soportado por formatos MP3, M4A y WMV):

var tags = new MediaFileTags
{
    Title = "Album Title Track",
    Performers = new[] { "Artist Name" },
    Album = "Album Name"
};

// Agregar carátula de álbum (plataformas Windows)
#if NET_WINDOWS
if (File.Exists("album_cover.jpg"))
{
    var albumArt = new System.Drawing.Bitmap("album_cover.jpg");
    tags.Pictures = new[] { albumArt };
    tags.Pictures_Descriptions = new[] { "Front Cover" };
}
#endif

var mp3Output = new MP3OutputBlock("track.mp3", mp3Settings, tags);

Modificación de Etiquetas en Tiempo de Ejecución¶

Modificar etiquetas durante la ejecución del pipeline:

var mp3Output = new MP3OutputBlock("output.mp3", mp3Settings);

// Etiquetas iniciales
mp3Output.Tags = new MediaFileTags
{
    Title = "Live Recording",
    Performers = new[] { "Artist" }
};

// Actualizar etiquetas antes de iniciar (por ejemplo, basado en entrada de usuario)
mp3Output.Tags.Comment = $"Grabado el {DateTime.Now:yyyy-MM-dd}";
mp3Output.Tags.Year = (uint)DateTime.Now.Year;

await pipeline.StartAsync();

Álbumes Multi-Pista¶

Crear metadatos consistentes en pistas de álbum:

public class AlbumRecorder
{
    private readonly MediaFileTags _baseAlbumTags;

    public AlbumRecorder()
    {
        _baseAlbumTags = new MediaFileTags
        {
            Album = "My Album",
            AlbumArtists = new[] { "Main Artist" },
            Year = 2025,
            Genres = new[] { "Pop", "Electronic" },
            TrackCount = 12,
            Copyright = "© 2025 Record Label"
        };
    }

    public void RecordTrack(int trackNumber, string title, string[] performers)
    {
        var trackTags = new MediaFileTags
        {
            // Copiar información base del álbum
            Album = _baseAlbumTags.Album,
            AlbumArtists = _baseAlbumTags.AlbumArtists,
            Year = _baseAlbumTags.Year,
            Genres = _baseAlbumTags.Genres,
            TrackCount = _baseAlbumTags.TrackCount,
            Copyright = _baseAlbumTags.Copyright,

            // Información específica de pista
            Track = (uint)trackNumber,
            Title = title,
            Performers = performers
        };

        var output = new MP3OutputBlock($"track_{trackNumber:D2}.mp3", mp3Settings, trackTags);

        // Continuar con configuración de pipeline...
    }
}

Mejores Prácticas¶

Calidad de Datos de Etiquetas¶

Codificación Consistente: Usar codificación UTF-8 para caracteres internacionales
Información Completa: Llenar tantos campos de etiquetas relevantes como sea posible
Géneros Estandarizados: Usar nombres de género reconocidos para mejor compatibilidad
Copyright Apropiado: Incluir avisos de copyright apropiados

Consideraciones de Rendimiento¶

Tamaño de Etiquetas: Mantener campos de texto de longitud razonable para evitar inflar archivos
Compresión de Imágenes: Comprimir carátulas de álbum apropiadamente (JPEG recomendado)
Procesamiento por Lotes: Reutilizar objetos de etiquetas cuando sea posible

Directrices Específicas de Formato¶

// MP3: ID3v2 soporta metadatos extensos
var mp3Tags = new MediaFileTags
{
    // Metadatos ricos totalmente soportados
    Title = "Song Title",
    Subtitle = "Song Subtitle", // Frame TIT3 de ID3v2.4
    Lyrics = "Texto completo de letras", // Frame USLT
    BeatsPerMinute = 128 // Frame TBPM
};

// OGG: Comentarios Vorbis son muy flexibles
var oggTags = new MediaFileTags
{
    // Todos los campos mapean bien a campos de comentario Vorbis
    Composers = new[] { "Composer 1", "Composer 2" }, // Valores múltiples soportados
    Performers = new[] { "Artist 1", "Artist 2" }
};

// M4A: Metadatos compatibles con iTunes
var m4aTagsForPodcast = new MediaFileTags
{
    Title = "Episode Title",
    Album = "Podcast Series Name", // Se muestra como "Album" en iTunes
    Performers = new[] { "Host Name" }, // Se muestra como "Artist"
    Genres = new[] { "Podcast" }, // Usar género "Podcast" para podcasts
    Comment = "Descripción del episodio"
};

Solución de Problemas¶

Problemas y Soluciones Comunes¶

Etiquetas no aparecen en reproductores de medios:

Asegurar que el formato de salida soporte los campos de etiquetas específicos que está usando
Verificar que el reproductor de medios soporte el formato de etiquetas (algunos reproductores prefieren ID3v2.3 sobre ID3v2.4)
Verificar que la codificación de texto sea correcta (UTF-8 recomendado)

Tamaño de archivo inesperadamente grande:

Reducir resolución de carátula de álbum (recomendado: máximo 600x600 píxeles)
Evitar campos de texto extremadamente largos en comentarios o letras
Usar compresión de imagen apropiada para carátulas

Errores de codificación:

Validar que caracteres especiales estén codificados apropiadamente
Asegurar que rutas de archivos sean accesibles y escribibles
Verificar que ajustes del codificador sean compatibles con su sistema

Depuración de Escritura de Etiquetas¶

var pipeline = new MediaBlocksPipeline();

// Habilitar registro detallado para ver procesamiento de etiquetas
pipeline.OnMessage += (sender, e) => 
{
    if (e.Message.Contains("tag") || e.Message.Contains("metadata"))
    {
        Console.WriteLine($"Depuración de Etiquetas: {e.Message}");
    }
};

// Continuar con configuración de pipeline...

Especificaciones de Formato de Etiquetas¶

Etiquetas ID3 (MP3)¶

ID3v1: Estructura básica de 128 bytes con campos limitados
ID3v2: Formato extensible soportando Unicode, valores múltiples y frames personalizados
Frames Comunes: TIT2 (Título), TPE1 (Artista), TALB (Álbum), TDRC (Año), TCON (Género)

Comentarios Vorbis (OGG)¶

Formato: Texto UTF-8 en formato NAME=VALUE
Campos Estándar: TITLE, ARTIST, ALBUM, DATE, GENRE, TRACKNUMBER
Flexible: Soporta nombres de campo arbitrarios y valores múltiples

Metadatos MP4 (M4A)¶

Átomos: Metadatos estilo iTunes almacenados en átomos MP4
Datos Binarios: Soporta carátulas incrustadas en átomo covr

Atributos ASF (WMV/WMA)¶

Estructura: Pares clave-valor en encabezado ASF
Estándar: Title, Author, Copyright, Description
Extendido: Atributos personalizados soportados

Esta guía completa demuestra cómo el SDK de VisioForge Media Blocks proporciona capacidades profesionales de escritura de metadatos de audio en todos los formatos de audio principales. La interfaz unificada MediaFileTags simplifica el proceso de desarrollo mientras asegura cumplimiento de estándares y compatibilidad óptima con reproductores de medios. Para más escenarios avanzados de procesamiento de audio y características adicionales del SDK, explore la documentación completa del SDK de VisioForge Media Blocks.