Lire un fichier multimédia dans Unity¶

Media Blocks SDK .Net Media Player SDK .Net

Il existe deux façons de lire un fichier local ou une URL réseau dans Unity, et le paquet fournit une scène prête pour chacune. Les deux s'affichent dans un RawImage Unity et fonctionnent sur Windows, Android, macOS Standalone et iOS. Cet article suppose que vous avez importé le paquet Unity et appliqué les deux réglages de projet requis — consultez d'abord Utiliser VisioForge dans Unity.

Deux scènes, deux moteurs¶

Choisissez SimplePlayer quand vous voulez assembler le pipeline vous-même ; choisissez MediaPlayerX quand vous voulez un moteur de lecture qui expose déjà les contrôles de transport. Les deux alimentent le même VisioForgeVideoView fourni, donc le chargement de texture, la gestion de l'aspect et le retournement vertical sont identiques.

SimplePlayer — le pipeline Media Blocks¶

La scène SimplePlayer lit un fichier vidéo local avec le Media Blocks SDK .NET de bas niveau et l'affiche dans un RawImage.

Lancer la scène SimplePlayer¶

1. Dans la fenêtre Project, ouvrez Assets/Scenes/SimplePlayer.unity (double-cliquez dessus).
2. Dans la Hierarchy, sélectionnez le GameObject RawImage. Le composant MediaBlocksPlayer y est attaché.
3. Dans l'Inspector, définissez File Path sur un chemin absolu vers un fichier multimédia local.
4. Appuyez sur ▶ Play — la vidéo apparaît dans la vue Game et l'audio est diffusé via le périphérique par défaut du système.

Champs de l'Inspector (MediaBlocksPlayer)¶

Le pipeline SimplePlayer¶

MediaBlocksPlayer construit ce pipeline :

graph LR;
    src[UniversalSourceBlock] -->|vidéo| sink["BufferSinkBlock (RGBA)"];
    sink --> view["VisioForgeVideoView (Texture2D)"];
    src -->|audio, optionnel| audio[AudioRendererBlock];

Le cœur de PlayAsync :

_pipeline = new MediaBlocksPipeline();

_videoSink = new BufferSinkBlock(VideoFormatX.RGBA);
_videoSink.OnVideoFrameBuffer += _videoView.OnFrameBuffer;

// ignoreMediaInfoReader:true ignore le pré-sondage du média (il peut échouer sous le
// runtime Unity) ; le codec est négocié au démarrage du pipeline.
var settings = await UniversalSourceSettings.CreateAsync(
    filePath, renderVideo: true, renderAudio: _renderAudio, ignoreMediaInfoReader: true);

_source = new UniversalSourceBlock(settings);
_pipeline.Connect(_source.VideoOutput, _videoSink.Input);

if (_renderAudio && _source.AudioOutput != null)
{
    _audioRenderer = new AudioRendererBlock();
    _pipeline.Connect(_source.AudioOutput, _audioRenderer.Input);
}

await _pipeline.StartAsync();

UniversalSourceBlock détecte automatiquement le conteneur et le codec. La branche audio n'est connectée que lorsque le fichier comporte un flux audio (_source.AudioOutput != null).

MediaPlayerX — le moteur MediaPlayerCoreX¶

La scène MediaPlayerX lit les mêmes fichiers et URL avec le moteur de haut niveau MediaPlayerCoreX. Contrairement au pipeline SimplePlayer câblé à la main, MediaPlayerCoreX vous offre un contrôle de lecture clé en main — lecture, pause, reprise, navigation, volume et vitesse de lecture — sans câblage manuel du pipeline.

L'événement OnVideoFrameUnity¶

MediaPlayerCoreX, VideoCaptureCoreX et VideoEditCoreX exposent un événement propre à Unity, OnVideoFrameUnity, qui livre chaque image d'aperçu en RGBA32 compacté (Stride == Width * 4, sans remplissage de ligne). Elle est chargée directement dans un Texture2D sans conversion de pixels. Abonnez-vous à cet événement avant d'ouvrir la source afin que le moteur intègre son capteur d'images interne dans le pipeline.

Exécuter la scène MediaPlayerX¶

1. Dans la fenêtre Project, ouvrez Assets/Scenes/SampleScene.unity.
2. Dans la Hierarchy, sélectionnez le GameObject RawImage — le composant MediaPlayerXPlayer y est attaché.
3. Dans l'Inspector, définissez File Path sur un chemin absolu ou une URL.
4. Appuyez sur ▶ Play — la vidéo apparaît dans la vue Game et l'audio est lu via le périphérique par défaut.

Champs de l'Inspector (MediaPlayerXPlayer)¶

Le pipeline MediaPlayerX¶

graph LR;
    player["MediaPlayerCoreX (headless)"] -->|OnVideoFrameUnity, RGBA32| view["VisioForgeVideoView (Texture2D)"];
    player -->|audio| out["Audio output device"];

Le cœur de PlayAsync :

_player = new MediaPlayerCoreX();

// Images RGBA32 prêtes pour la texture, directement dans la vue.
_player.OnVideoFrameUnity += _videoView.OnFrameBuffer;

// MediaPlayerCoreX ne rend l'audio que lorsqu'un périphérique de sortie est défini.
var outputs = await _player.Audio_OutputDevicesAsync();
if (outputs != null && outputs.Length > 0)
{
    _player.Audio_OutputDevice = new AudioRendererSettings(outputs[0]);
    _player.Audio_OutputDevice_Volume = 1.0;
}

// ignoreMediaInfoReader:true ignore la pré-analyse du média (elle peut échouer sous le runtime Unity).
var source = await UniversalSourceSettings.CreateAsync(
    filePath, renderVideo: true, renderAudio: true, renderSubtitle: false,
    deepDiscovery: false, ignoreMediaInfoReader: true);

await _player.OpenAsync(source);
await _player.PlayAsync();

PauseAsync, ResumeAsync et Position_SetAsync(TimeSpan) vous offrent le contrôle du transport ; l'exemple les expose sous la forme PauseAsync(), ResumeAsync() et SeekAsync(position).

L'utiliser dans votre propre scène¶

Vous n'êtes pas obligé d'utiliser une scène d'exemple :

1. Ajoutez un Canvas → Raw Image (GameObject → UI → Raw Image).
2. Sélectionnez le Raw Image et Add Component → MediaBlocksPlayer (pipeline Media Blocks) ou MediaPlayerXPlayer (moteur MediaPlayerCoreX).
3. Définissez File Path et appuyez sur ▶ Play.

La gestion de l'aspect (Stretch / Letterbox / Crop), la disposition du RawImage et le retournement vertical sont pris en charge pour vous par le VisioForgeVideoView fourni — vous n'écrivez aucun code de texture. Pour basculer le même GameObject vers la lecture RTSP, utilisez RTSPViewerPlayer ou IPCameraXViewer (voir Afficher une caméra RTSP).

Réglages de build par plateforme¶

Les deux scènes s'exécutent sans modification sur chaque plateforme prise en charge. Basculez Build Target et appliquez les réglages correspondants :

Foire aux questions¶

Quelle scène utiliser — SimplePlayer ou MediaPlayerX ?¶

Utilisez SimplePlayer (MediaBlocksPipeline) quand vous voulez construire le pipeline vous-même — ajouter des effets, plusieurs sinks, l'enregistrement ou des sources personnalisées. Utilisez MediaPlayerX (MediaPlayerCoreX) quand vous voulez un moteur de lecture qui fournit déjà la navigation, la pause/reprise, la durée, la sélection du périphérique audio et le contrôle de vitesse sous forme de méthodes clé en main.

Quels formats vidéo et audio peut-il lire ?¶

Le paquet embarque FFmpeg/libav, les formats courants se décodent donc d'emblée — MP4, MKV, AVI, MOV avec H.264/H.265, MPEG-4, ainsi que l'audio MP3/AAC, entre autres. Les deux moteurs détectent automatiquement le format.

Peut-il lire des flux réseau ?¶

Oui. MediaPlayerX prend une URL http/https/rtsp/hls directement dans File Path (UniversalSourceSettings gère à la fois les fichiers locaux et les URL). SimplePlayer lit des fichiers locaux ; pour un pipeline de caméra en direct dédié, voir Afficher une caméra RTSP.

Comment naviguer ou mettre en pause ?¶

Sur MediaPlayerX, appelez SeekAsync(TimeSpan), PauseAsync() et ResumeAsync() sur le composant — ils encapsulent Position_SetAsync, PauseAsync et ResumeAsync sur MediaPlayerCoreX. Le SimplePlayer de bas niveau n'expose pas de contrôles de transport ; reconstruisez le pipeline pour changer de source.

Pourquoi MediaPlayerX doit-il définir un périphérique de sortie audio ?¶

MediaPlayerCoreX ne rend l'audio que lorsque Audio_OutputDevice est défini. L'exemple énumère les périphériques de sortie avec Audio_OutputDevicesAsync() et sélectionne le premier. SimplePlayer achemine plutôt l'audio via un AudioRendererBlock.

Comment contrôler l'adaptation de la vidéo au RawImage ?¶

Utilisez le champ Aspect Mode sur l'un ou l'autre composant : Stretch (remplissage, peut déformer), Letterbox (adaptation avec bandes) ou Crop (remplissage avec rognage du débordement).

Voir aussi¶

• Utiliser VisioForge dans Unity — présentation du paquet, configuration et fonctionnement du rendu
• Afficher une caméra RTSP dans Unity — les scènes RTSP / caméra IP en direct
• Capturer une webcam dans Unity — l'exemple d'enregistreur VideoCaptureCoreX
• Éditer et rendre dans Unity — l'exemple de montage VideoEditCoreX
• Présentation du Media Blocks SDK .NET — le catalogue complet des blocs