Пакет javafx.scene.media

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

Содержание

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

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

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

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

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

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

Кодирование	Тип	Описание
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)
H.265/HEVC	Видео	Видеосжатие H.265/MPEG-H Part 2 / HEVC (High Efficiency Video Coding)

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

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

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

Контейнер	Описание	Видеокодирование	Аудиокодирование	Тип 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
HLS (*)	fMP4 HTTP Live Streaming (аудиовизуальный)	H.264/AVC	AAC	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
HLS (*)	fMP4 HTTP Live Streaming (аудиовизуальный)	H.265/HEVC	AAC	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
HLS (*)	fMP4 HTTP Live Streaming (только аудио)	N/A	AAC	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
HLS (*)	AAC HTTP Live Streaming (только аудио)	N/A	AAC	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
MP4	MPEG-4 Part 14	H.265/HEVC	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 делает метаданные доступными через метод Media.getMetadata(). Ключи в этом отображении называются *тегами*, и поддерживаемые Java FX Media теги перечислены в следующей таблице. Обратите внимание, что доступность тегов для данного источника медиа зависит от фактически хранимых в нём метаданных, т.е. не все теги гарантируются.

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

Контейнер	Тег (тип String)	Тип	Описание
MP3	raw metadata	Map<String,ByteBuffer>	Необработанные метаданные в соответствии с соответствующим спецификацией медиа. Ключ "ID3" сопоставляется с метаданными MP3 ID3v2.
MP3	album artist	java.lang.String	Исполнитель для всего альбома, возможно «Разные исполнители» для сборников.
MP3	album	java.lang.String	Название альбома.
MP3	artist	java.lang.String	Исполнитель трека.
MP3	comment-N	java.lang.String	Комментарий, где N — индекс с нулевым значением. Формат комментария: 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	Жанр трека, например, «Классика», «Darkwave» или «Джаз».
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 Media могут быть синхронными или асинхронными. В общем случае синхронные ошибки проявляются как 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.
     }