javafx.scene.media.Media Maven / Gradle / Ivy
/*
* Copyright (c) 2010, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javafx.scene.media;
import com.sun.media.jfxmedia.MetadataParser;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.FileNotFoundException;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import javafx.application.Platform;
import javafx.beans.NamedArg;
import javafx.beans.property.ObjectProperty;
import javafx.beans.property.ObjectPropertyBase;
import javafx.collections.FXCollections;
import javafx.collections.ObservableList;
import javafx.collections.ObservableMap;
import javafx.scene.image.Image;
import javafx.util.Duration;
import com.sun.media.jfxmedia.locator.Locator;
import javafx.beans.property.ReadOnlyIntegerProperty;
import javafx.beans.property.ReadOnlyIntegerWrapper;
import javafx.beans.property.ReadOnlyObjectProperty;
import javafx.beans.property.ReadOnlyObjectWrapper;
import com.sun.media.jfxmedia.events.MetadataListener;
/**
* The Media class represents a media resource. It is instantiated
* from the string form of a source URI. Information about the media such as
* duration, metadata, tracks, and video resolution may be obtained from a
* Media instance. The media information is obtained asynchronously
* and so not necessarily available immediately after instantiation of the class.
* All information should however be available if the instance has been
* associated with a {@link MediaPlayer} and that player has transitioned to
* {@link MediaPlayer.Status#READY} status. To be notified when metadata or
* {@link Track}s are added, observers may be registered with the collections
* returned by {@link #getMetadata()}and {@link #getTracks()}, respectively.
*
* The same Media object may be shared among multiple
* MediaPlayer objects. Such a shared instance might manage a single
* copy of the source media data to be used by all players, or it might require a
* separate copy of the data for each player. The choice of implementation will
* not however have any effect on player behavior at the interface level.
*
* @see MediaPlayer
* @see MediaException
* @since JavaFX 2.0
*/
public final class Media {
/**
* A property set to a MediaException value when an error occurs.
* If error is non-null, then the media could not
* be loaded and is not usable. If {@link #onErrorProperty onError} is non-null,
* it will be invoked when the error property is set.
*
* @see MediaException
*/
private ReadOnlyObjectWrapper error;
private void setError(MediaException value) {
if (getError() == null) {
errorPropertyImpl().set(value);
}
}
/**
* Return any error encountered in the media.
* @return a {@link MediaException} or null if there is no error.
*/
public final MediaException getError() {
return error == null ? null : error.get();
}
public ReadOnlyObjectProperty errorProperty() {
return errorPropertyImpl().getReadOnlyProperty();
}
private ReadOnlyObjectWrapper errorPropertyImpl() {
if (error == null) {
error = new ReadOnlyObjectWrapper<>() {
@Override
protected void invalidated() {
if (getOnError() != null) {
Platform.runLater(getOnError());
}
}
@Override
public Object getBean() {
return Media.this;
}
@Override
public String getName() {
return "error";
}
};
}
return error;
}
/**
* Event handler called when an error occurs. This will happen
* if a malformed or invalid URL is passed to the constructor or there is
* a problem accessing the URL.
*/
private ObjectProperty onError;
/**
* Set the event handler to be called when an error occurs.
* @param value the error event handler.
*/
public final void setOnError(Runnable value) {
onErrorProperty().set(value);
}
/**
* Retrieve the error handler to be called if an error occurs.
* @return the error handler or null if none is defined.
*/
public final Runnable getOnError() {
return onError == null ? null : onError.get();
}
public ObjectProperty onErrorProperty() {
if (onError == null) {
onError = new ObjectPropertyBase<>() {
@Override
protected void invalidated() {
/*
* if we have an existing error condition schedule the handler to be
* called immediately. This way the client app does not have to perform
* an explicit error check.
*/
if (get() != null && getError() != null) {
Platform.runLater(get());
}
}
@Override
public Object getBean() {
return Media.this;
}
@Override
public String getName() {
return "onError";
}
};
}
return onError;
}
private MetadataListener metadataListener = new _MetadataListener();
/**
* An {@link ObservableMap} of metadata which can contain information about
* the media. Metadata entries use {@link String}s for keys and contain
* {@link Object} values. This map is unmodifiable: its contents or stored
* values cannot be changed.
*/
// FIXME: define standard metadata keys and the corresponding objects types
// FIXME: figure out how to make the entries read-only to observers, we'll
// need to enhance javafx.collections a bit to accomodate this
private ObservableMap metadata;
/**
* Retrieve the metadata contained in this media source. If there are
* no metadata, the returned {@link ObservableMap} will be empty.
* @return the metadata contained in this media source.
*/
public final ObservableMap getMetadata() {
return metadata;
}
private final ObservableMap metadataBacking = FXCollections.observableMap(new HashMap());
/**
* The width in pixels of the source media.
* This may be zero if the media has no width, e.g., when playing audio,
* or if the width is currently unknown which may occur with streaming
* media.
* @see height
*/
private ReadOnlyIntegerWrapper width;
final void setWidth(int value) {
widthPropertyImpl().set(value);
}
/**
* Retrieve the width in pixels of the media.
* @return the media width or zero if the width is undefined or unknown.
*/
public final int getWidth() {
return width == null ? 0 : width.get();
}
public ReadOnlyIntegerProperty widthProperty() {
return widthPropertyImpl().getReadOnlyProperty();
}
private ReadOnlyIntegerWrapper widthPropertyImpl() {
if (width == null) {
width = new ReadOnlyIntegerWrapper(this, "width");
}
return width;
}
/**
* The height in pixels of the source media.
* This may be zero if the media has no height, e.g., when playing audio,
* or if the height is currently unknown which may occur with streaming
* media.
* @see width
*/
private ReadOnlyIntegerWrapper height;
final void setHeight(int value) {
heightPropertyImpl().set(value);
}
/**
* Retrieve the height in pixels of the media.
* @return the media height or zero if the height is undefined or unknown.
*/
public final int getHeight() {
return height == null ? 0 : height.get();
}
public ReadOnlyIntegerProperty heightProperty() {
return heightPropertyImpl().getReadOnlyProperty();
}
private ReadOnlyIntegerWrapper heightPropertyImpl() {
if (height == null) {
height = new ReadOnlyIntegerWrapper(this, "height");
}
return height;
}
/**
* The duration in seconds of the source media. If the media duration is
* unknown then this property value will be {@link Duration#UNKNOWN}.
*/
private ReadOnlyObjectWrapper duration;
final void setDuration(Duration value) {
durationPropertyImpl().set(value);
}
/**
* Retrieve the duration in seconds of the media.
* @return the duration of the media, {@link Duration#UNKNOWN} if unknown or {@link Duration#INDEFINITE} for live streams
*/
public final Duration getDuration() {
return duration == null || duration.get() == null ? Duration.UNKNOWN : duration.get();
}
public ReadOnlyObjectProperty durationProperty() {
return durationPropertyImpl().getReadOnlyProperty();
}
private ReadOnlyObjectWrapper durationPropertyImpl() {
if (duration == null) {
duration = new ReadOnlyObjectWrapper<>(this, "duration");
}
return duration;
}
/**
* An ObservableList of tracks contained in this media object.
* A Media object can contain multiple tracks, such as a video track
* with several audio track. This list is unmodifiable: the contents cannot
* be changed.
* @see Track
*/
private ObservableList