Пакет 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)
H.265/HEVC	Видео	Видеосжатие H.265/MPEG-H Part 2 / HEVC (High Efficiency Video Coding)

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

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

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

Контейнер	Описание	Видео-кодирование	Аудио-кодирование	Тип MIME	Расширение файла
AIFF	Аудиоформат Interchange File Format	N/A	PCM	audio/x-aiff	.aif, .aiff
HLS (*)	HTTP Live Streaming (мультимедиа) MP2T	H.264/AVC	AAC	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
HLS (*)	HTTP Live Streaming (только аудио) MP3	N/A	MP3	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
HLS (*)	HTTP Live Streaming (мультимедиа) fMP4	H.264/AVC	AAC	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
HLS (*)	HTTP Live Streaming (мультимедиа) fMP4	H.265/HEVC	AAC	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
HLS (*)	HTTP Live Streaming (только аудио) fMP4	N/A	AAC	application/vnd.apple.mpegurl, audio/mpegurl	.m3u8
HLS (*)	HTTP Live Streaming (только аудио) AAC	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	Формат Waveform Audio	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	HTTP Live Streaming (RFC 8216)

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

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

HTTP Live Streaming (HLS)

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

• Плейлисты для запросов и прямых трансляций.
• Элементарные аудиопотоки MP3 и AAC (audio/mpegurl).
• Мультиплексированные потоки MP2T (application/vnd.apple.mpegurl) с одним аудиопотоком AAC и одним видеопотоком H.264/AVC.
• Мультиплексированные потоки fMP4 (application/vnd.apple.mpegurl) с одним аудиопотоком AAC и одним видеопотоком H.264/AVC или H.265/HEVC.
• Плейлисты с целыми или дробными значениями продолжительности.
• Дополнительные аудиоканала через тег #EXT-X-MEDIA:
  • Потоки MP2T с одним видеопотоком H.264/AVC и элементарным аудиопотоком AAC через тег #EXT-X-MEDIA.
  • Потоки fMP4 с одним видеопотоком H.264/AVC или H.265/HEVC и элементарным аудиопотоком AAC через тег #EXT-X-MEDIA.
  • Потоки fMP4 с одним видеопотоком H.264/AVC или H.265/HEVC и потоками fMP4 с одним аудиопотоком AAC через тег #EXT-X-MEDIA.

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

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

Контейнер медиа также может содержать определённые метаданные, описывающие медиа в файле. 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 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.
     }