Пакет javafx.scene.media

Предоставляет набор классов для интеграции аудио и видео в приложения Java FX. Основное применение этого пакета — воспроизведение медиа. В этом пакете есть три основных класса: Media, MediaPlayer и MediaView.

Содержание

1. Поддерживаемые типы медиа
2. Поддерживаемые протоколы
3. Поддерживаемые теги метаданных
4. Воспроизведение медиа в Java FX

Поддерживаемые типы медиа

Java FX поддерживает множество различных типов медиа. Тип медиа рассматривается как комбинация формата контейнера и одного или нескольких кодирований. В некоторых случаях формат контейнера может быть просто элементарным потоком, содержащим закодированные данные.

Поддерживаемые типы кодирования

Тип кодирования определяет, как хранятся сэмплированные аудио- или видеоданные. Обычно тип кодирования подразумевает определённый алгоритм сжатия. В следующей таблице указаны типы кодирования, поддерживаемые медиа Java FX.

Таблица кодирования медиа

Кодирование	Тип	Описание
AAC	Аудио	Аудиосжатие с использованием Advanced Audio Coding
MP3	Аудио	Сырые аудиопотоки MPEG-1, 2 и 2.5; слои I, II и III; все поддерживаемые комбинации частот дискретизации и битрейтов. Примечание: файл должен содержать как минимум 3 кадра MP3.
PCM	Аудио	Несжатые, сырые аудиосэмплы
H.264/AVC	Видео	Видеосжатие H.264/MPEG-4 Part 10 / AVC (Advanced Video Coding)

Поддерживаемые типы контейнеров

Тип контейнера определяет формат файла, используемый для хранения закодированных аудио-, видео- и других медиаданных. Каждый тип контейнера связан с одним или несколькими типами MIME, расширениями файлов и сигнатурами файлов (начальные байты в файле). В следующей таблице указаны комбинации типов контейнеров и кодирования, поддерживаемые медиа Java FX.

Таблица типов контейнеров/кодирования медиа

Контейнер	Описание	Видеокодирование	Аудиокодирование	Тип MIME	Расширение файла
AIFF	Формат файла обмена аудио	N/A	PCM	audio/x-aiff	.aif, .aiff
HLS (*)	MP2T HTTP Live Streaming (аудиовизуальный)	H.264/AVC	AAC	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
HLS (*)	MP3 HTTP Live Streaming (только аудио)	N/A	MP3	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
MP3	MPEG-1, 2, 2.5 сырой аудиопоток, возможно с метаданными ID3 v2.3 или v2.4	N/A	MP3	audio/mpeg	.mp3
MP4	MPEG-4 Part 14	H.264/AVC	AAC	video/mp4, audio/x-m4a, video/x-m4v	.mp4, .m4a, .m4v
WAV	Формат аудиоволны	N/A	PCM	audio/x-wav	.wav

(*) HLS — это протокол, а не тип контейнера, но он включён сюда для агрегирования подобных атрибутов.

Поддерживаемые протоколы

Таблица поддерживаемых протоколов

Протокол	Описание	Ссылка
FILE	Протокол для представления URI локальных файлов	java.net.URI
HTTP	Протокол передачи гипертекста для представления удалённых файлов	java.net.URI
HTTPS	Протокол передачи гипертекста по защищённому каналу для представления удалённых файлов	java.net.URI
JAR	Представление записей медиа в файлах, доступных через протоколы FILE, HTTP или HTTPS	java.net.JarURLConnection
HTTP Live Streaming (HLS)	Потоковая передача медиа на основе плейлистов через HTTP или HTTPS	Internet-Draft: HTTP Live Streaming

Воспроизведение MPEG-4 через HTTP

Рекомендуется, чтобы MPEG-4 медиа, воспроизводимые через HTTP или HTTPS, были отформатированы таким образом, чтобы необходимые для декодирования потока заголовки появлялись в начале файла. В противном случае воспроизведение может приостановиться, пока весь файл не будет загружен.

HTTP Live Streaming (HLS)

Воспроизведение HLS обрабатывает источники с такими характеристиками:

• Плейлисты по запросу и в прямом эфире.
• Элементарные аудиопотоки MP3 (audio/mpegurl) и мультиплексированные потоки MP2T (application/vnd.apple.mpegurl) с одним аудио AAC и одним видео H.264/AVC.
• Плейлисты с целочисленной или плавающей точкой длительностью.

Источники, которые не соответствуют этому базовому профилю, не гарантируют обработки. Плейлист содержит информацию о потоках, составляющих источник, и загружается в начале воспроизведения. Переключение между альтернативными потоками, битрейтами и разрешениями видео автоматически обрабатывается в зависимости от сетевых условий.

Поддерживаемые теги метаданных

Контейнер медиа может также содержать определённые метаданные, описывающие медиа в файле. API медиа Java FX предоставляет доступ к метаданным через метод Media.getMetadata(). Ключи в этом отображении называются тегами, и поддерживаемые Java FX Media теги перечислены в следующей таблице. Обратите внимание, что доступные теги для данного источника медиа зависят от фактически хранящихся в нём метаданных, то есть не все теги гарантированно доступны.

Таблица ключей и тегов метаданных

Контейнер	Тег (тип String)	Тип	Описание
MP3	raw metadata	Map<String,ByteBuffer>	Сырые метаданные в соответствии с соответствующим спецификацией медиа. Ключ "ID3" сопоставляется с метаданными MP3 ID3v2.
MP3	album artist	java.lang.String	Исполнитель всего альбома, возможно, «Various Artists» для сборников.
MP3	album	java.lang.String	Название альбома.
MP3	artist	java.lang.String	Исполнитель трека.
MP3	comment-N	java.lang.String	Комментарий, где N — индекс отсчёта 0. Формат комментария: ContentDescription[lng]=Comment
MP3	composer	java.lang.String	Композитор трека.
MP3	year	java.lang.Integer	Год записи трека.
MP3	disc count	java.lang.Integer	Количество дисков в альбоме.
MP3	disc number	java.lang.Integer	Индекс диска (с отсчётом с 1), на котором появляется этот трек.
MP3	duration	javafx.util.Duration	Продолжительность трека.
MP3	genre	java.lang.String	Жанр трека, например, «Классическая музыка», «Драмвейв» или «Джаз».
MP3	image	javafx.scene.image.Image	Обложка альбома.
MP3	title	java.lang.String	Название трека.
MP3	track count	java.lang.Integer	Количество треков в альбоме.
MP3	track number	java.lang.Integer	Индекс трека (с отсчётом с 1) на диске.

Воспроизведение медиа в Java FX

Базовое воспроизведение

Основные шаги, необходимые для воспроизведения медиа в Java FX:

1. Создайте объект Media для выбранного источника медиа.
2. Создайте объект MediaPlayer из объекта Media.
3. Создайте объект MediaView.
4. Добавьте MediaPlayer в MediaView.
5. Добавьте MediaView в граф сцены.
6. Вызовите MediaPlayer.play().

Эти шаги проиллюстрированы примером кода в документации класса MediaView. Следует отметить следующее:

• Один объект Media может быть совместно использован несколькими объектами MediaPlayer.
• Один объект MediaPlayer может быть совместно использован несколькими объектами MediaView.
• Медиа можно воспроизводить непосредственно с помощью объекта MediaPlayer без создания объекта MediaView, хотя для отображения требуется представление.
• Вместо MediaPlayer.play() можно использовать MediaPlayer.setAutoPlay(true) для запроса начала воспроизведения как можно скорее.
• Объект MediaPlayer имеет несколько рабочих состояний, определённых перечислением MediaPlayer.Status.
• Аудио-только медиа можно воспроизводить с помощью класса AudioClip (рекомендуется для воспроизведения коротких фрагментов с низкой задержкой).

Обработка ошибок

Ошибки при использовании медиа Java FX могут быть синхронными или асинхронными. В общем случае синхронные ошибки проявятся как ошибка Java Exception, а асинхронные ошибки приведут к установке свойства Java FX. В последнем случае можно либо напрямую наблюдать за свойством error, зарегистрировать обратный вызов onError, либо сделать и то, и другое.

Основными источниками синхронных ошибок являются Media() и MediaPlayer(). Асинхронные свойства ошибок — это Media.error и MediaPlayer.error, а асинхронные обратные вызовы ошибок — Media.onError, MediaPlayer.onError и MediaView.onError.

Некоторые ошибки могут быть дублированы. Например, MediaPlayer будет распространять ошибку, с которой она столкнулась, своему связанному Media, а MediaPlayer — всем своим связанным MediaView. Вследствие этого, возможно получение нескольких уведомлений о возникновении данной ошибки в зависимости от отслеживаемых свойств.

Следующий фрагмент кода демонстрирует обработку ошибок с использованием медиа:

    String source;
    Media media;
    MediaPlayer mediaPlayer;
    MediaView mediaView;
    try {
        media = new Media(source);
        if (media.getError() == null) {
            media.setOnError(new Runnable() {
                public void run() {
                    // Handle asynchronous error in Media object.
                }
            });
            try {
                mediaPlayer = new MediaPlayer(media);
                if (mediaPlayer.getError() == null) {
                    mediaPlayer.setOnError(new Runnable() {
                        public void run() {
                            // Handle asynchronous error in MediaPlayer object.
                        }
                    });
                    mediaView = new MediaView(mediaPlayer);
                    mediaView.setOnError(new EventHandler<MediaErrorEvent>() {
                        public void handle(MediaErrorEvent t) {
                            // Handle asynchronous error in MediaView.
                        }
                    });
                } else {
                    // Handle synchronous error creating MediaPlayer.
                }
            } catch (Exception mediaPlayerException) {
                // Handle exception in MediaPlayer constructor.
            }
        } else {
            // Handle synchronous error creating Media.
        }
    } catch (Exception mediaException) {
        // Handle exception in Media constructor.
    }