Module  javafx.media
软件包  javafx.scene.media

Class MediaPlayer


  • public final class MediaPlayer
extends Object
    MediaPlayer类提供播放媒体的控件。 它与Media和MediaView类结合使用以显示和控制媒体播放。 MediaPlayer不包含任何视觉元素，所以必须与MediaView类一起使用，以查看可能存在的任何视频轨道。

    MediaPlayer提供pause() ， play() ， stop()和seek()控制以及所述rate个autoPlay适用于所有类型的媒体属性。 它还提供了balance ， mute和volume性质，这控制音频重放特性。 通过与播放器相关联的AudioEqualizer可以进一步控制音频质量。 通过注册AudioSpectrumListener可以观察到音频播放的频率描述符。 关于重放位置，速率和缓存信息可以从获得currentTime ， currentRate ，和bufferProgressTime性质分别。 媒体标记通知由注册为onMarker属性的事件处理程序接收。

    对于有限持续时间的媒体，播放可以位于0.0与媒体持续时间之间的任何时间点。 MediaPlayer通过添加startTime和stopTime属性来优化此定义，该属性实际上定义了时间位置限制为[startTime,stopTime]的虚拟媒体源。 媒体播放开始于startTime并继续到stopTime 。 由这两个端点所定义的间隔被称为具有持续时间是停止的差和开始时间的循环 。 该循环可以设置为重复特定的或不定期的次数。 媒体播放的总持续时间是周期持续时间和播放次数的乘积。 如果达到循环的停止时间并重新播放周期，则调用注册在onRepeat属性中的事件处理程序。 如果达到停止时间并且不重复循环，则调用注册到onEndOfMedia属性的事件处理程序。 目前正在播放的循环的零相关指数由currentCount维护。

    MediaPlayer的操作MediaPlayer是异步的。 播放器不准备立即响应命令，直到其状态转变为MediaPlayer.Status.READY ，这通常在媒体前贴片完成时发生。 在播放器状态为READY之前发出的一些请求将在输入该状态时生效。 这些包括调用play()无居间调用pause()或stop()的前READY过渡，以及设置任何的autoPlay ， balance ， mute ， rate ， startTime ， stopTime ，和volume性质。

    可以监视status属性以使应用程序知道播放器状态更改，如果在输入特定状态时应采取措施，则可以通过属性（如onReady）注册回调函数。 还有error和onError属性，分别可以在发生错误时进行监视并对其作出响应。

    相同的MediaPlayer对象可以在多个MediaView之间共享。 这不会影响玩家本身。 特别地，视图的属性设置不会对媒体播放产生任何影响。

    从以下版本开始：
    JavaFX 2.0
    另请参见：
    Media ， MediaView

    • 字段详细信息

      • INDEFINITE

        public static final int INDEFINITE
        表示有效无限数量的回放周期的值。 当cycleCount设置为此值时，播放器将重播Media直到停止或暂停。
        另请参见：
        Constant Field Values

    • 构造方法详细信息

      • MediaPlayer

        public MediaPlayer​(Media media)
        为特定媒体创建播放器。 这是将Media对象与MediaPlayer关联的唯一方法：一旦播放器被创建，它就无法更改。 在构造函数中同步发生的错误将导致抛出异常。 异步发生的错误将导致error属性被设置，因此任何onError回调被调用。

        创建时，播放器的status将为MediaPlayer.Status.UNKNOWN 。 一旦status已经转换为MediaPlayer.Status.READY ，玩家将处于可用状态。 播放器创建与其进入READY状态之间的时间量可能会有所不同，具体取决于例如媒体是通过网络连接还是从本地文件系统读取。

        参数
        media - 媒体玩。
        异常
        NullPointerException - 如果媒体是 null 。
        MediaException - 如果在构造函数中发生任何同步错误。

    • 方法详细信息

      • getAudioEqualizer

        public final AudioEqualizer getAudioEqualizer​()
        检索与此播放器相关联的AudioEqualizer 。
        结果
        AudioEqualizer或 null如果玩家被处置。

      • getError

        public final MediaException getError​()
        检索 error属性的值或 null如果没有错误。
        结果
        一个 MediaException或 null 。

      • setOnError

        public final void setOnError​(Runnable value)
        设置发生错误时调用的事件处理程序。
        参数
        value - 事件处理程序或 null 。

      • getOnError

        public final Runnable getOnError​()
        检索错误的事件处理程序。
        结果
        事件处理程序。

      • getMedia

        public final Media getMedia​()
        检索正在播放的Media实例。
        结果
        Media对象。

      • setAutoPlay

        public final void setAutoPlay​(boolean value)
        设置 autoPlay属性值。
        参数
        value - 是否启用自动播放

      • isAutoPlay

        public final boolean isAutoPlay​()
        检索 autoPlay属性值。
        结果
        价值。

      • autoPlayProperty

        public BooleanProperty autoPlayProperty​()
        是否应尽快开始播放。 对于新的玩家来说，一旦玩家达到就绪状态，这个玩家就会发生这种情况。 默认值为false 。
        另请参见：
        isAutoPlay() ， setAutoPlay(boolean)

      • play

        public void play​()
        开始播放媒体。 如果先前已暂停，则播放将恢复暂停。 如果播放停止，播放从startTime开始。 当玩实际启动时， status将设置为MediaPlayer.Status.PLAYING 。

      • setRate

        public final void setRate​(double value)
        将播放速度设置为提供的值。 其效果将被钳位在[0.0, 8.0]范围内。 如果媒体持续时间为Duration.INDEFINITE，则调用此方法将不起作用 。
        参数
        value - 播放速度

      • getRate

        public final double getRate​()
        检索播放速度。
        结果
        播放速度

      • rateProperty

        public DoubleProperty rateProperty​()
        要播放媒体的速度。 例如， 1.0的频率以其正常（编码）播放速率播放媒体， 2.0以正常速率的两倍播放，等等。目前支持的频率范围是[0.0, 8.0] 。 默认值为1.0 。
        另请参见：
        getRate() ， setRate(double)

      • getCurrentRate

        public final double getCurrentRate​()
        检索当前播放速率。
        结果
        目前的汇率

      • currentRateProperty

        public ReadOnlyDoubleProperty currentRateProperty​()
        当前的播放速度，无论设置如何。 例如，如果rate设置为1.0，播放器暂停或停止，则currentRate将为零。
        另请参见：
        getCurrentRate()

      • setVolume

        public final void setVolume​(double value)
        设置音频播放音量。 其效果将被夹紧到[0.0, 1.0]的范围内。
        参数
        value - 音量

      • getVolume

        public final double getVolume​()
        检索音频播放音量。 默认值为1.0 。
        结果
        音频音量

      • volumeProperty

        public DoubleProperty volumeProperty​()
        要播放媒体的音量。 有效值范围为[0.0 1.0] ，其中0.0为听不到， 1.0为全音量，为默认值。
        另请参见：
        getVolume() ， setVolume(double)

      • setBalance

        public final void setBalance​(double value)
        设置音频平衡。 其效果将被夹紧到[-1.0, 1.0]的范围内。
        参数
        value - 余额

      • getBalance

        public final double getBalance​()
        检索音频平衡。
        结果
        音频平衡

      • balanceProperty

        public DoubleProperty balanceProperty​()
        音频输出的平衡或左右设置。 有效的值的范围是[-1.0, 1.0]与-1.0充满左， 0.0中心，和1.0充分权利。 默认值为0.0 。
        另请参见：
        getBalance() ， setBalance(double)

      • getStartTime

        public final Duration getStartTime​()
        检索开始时间。 默认值为Duration.ZERO 。
        结果
        开始时间

      • startTimeProperty

        public ObjectProperty<Duration> startTimeProperty​()
        媒体应该开始播放的时间偏移，或重复播放时重新启动。 当播放停止时，当前时间被重置为该值。 如果该值为正，则播放前第一次播放媒体可能会有延迟，除非播放位置可以设置为媒体内的任意时间。 这可能例如对于不包含视频流中的帧内偏移的查找表的视频而言。 在这种情况下，视频帧将需要被跳过直到达到开始时间之前的第一帧内的位置。 默认值为Duration.ZERO 。

        约束： 0 ≤ startTime < stopTime

        另请参见：
        getStartTime() ， setStartTime(Duration)

      • getStopTime

        public final Duration getStopTime​()
        检索停止时间。 默认值为getMedia().getDuration() 。 请注意，如果媒体初始化未完成，则Media.duration可能具有值Duration.UNKNOWN 。
        结果
        停止时间

      • getCycleDuration

        public final Duration getCycleDuration​()
        以秒为单位检索循环持续时间。
        结果
        循环持续时间

      • getTotalDuration

        public final Duration getTotalDuration​()
        检索总播放持续时间，包括所有周期（重复）。
        结果
        总播放时间

      • totalDurationProperty

        public ReadOnlyObjectProperty<Duration> totalDurationProperty​()
        播放时间的总量，如果允许玩，直到完成。 如果cycleCount设置为INDEFINITE那么这也将是INDEFINITE。 如果Media持续时间为UNKNOWN，则同样为UNKNOWN。 否则，总持续时间将是cycleDuration和cycleCount的乘积。
        另请参见：
        getTotalDuration()

      • getCurrentTime

        public final Duration getCurrentTime​()
        检索当前媒体时间。
        结果
        当前媒体时间

      • seek

        public void seek​(Duration seekTime)
        寻找播放器一个新的播放时间。 当播放器状态为MediaPlayer.Status.STOPPED或媒体持续时间为Duration.INDEFINITE时，调用此方法将不起作用 。

        seek()的行为约束如下，其中开始时间和停止时间分别表示媒体播放的有效下限和上限：

        MediaPlayer Seek Table seekTime seek position null no change Duration.UNKNOWN no change Duration.INDEFINITE stop time seekTime < start time start time seekTime > stop time stop time start time ≤ seekTime ≤ stop time seekTime
        参数
        seekTime - 请求的播放时间

      • getStatus

        public final MediaPlayer.Status getStatus​()
        检索当前播放器的状态。
        结果
        播放状态

      • bufferProgressTimeProperty

        public ReadOnlyObjectProperty<Duration> bufferProgressTimeProperty​()
        当前的缓冲位置指示可以播放多少媒体，而不会停止MediaPlayer 。 这适用于缓冲流，例如从网络连接读取的流，而不是本地文件。

        寻求超出bufferProgressTime的位置可能会导致播放中轻微的暂停，直到足够数量的允许播放恢复的数据被缓存。

        另请参见：
        getBufferProgressTime()

      • getCycleCount

        public final int getCycleCount​()
        检索周期数。
        结果
        周期数。

      • cycleCountProperty

        public IntegerProperty cycleCountProperty​()
        媒体播放的次数。 默认情况下， cycleCount设置为1这意味着媒体只能播放一次。 将cycleCount设置为大于1的值将导致介质播放给定次数或直到停止。 如果设置为INDEFINITE ，播放将重复，直到调用stop（）或pause（）为止。

        约束： cycleCount ≥ 1

        另请参见：
        getCycleCount() ， setCycleCount(int)

      • getCurrentCount

        public final int getCurrentCount​()
        检索当前周期的索引。
        结果
        当前周期指数

      • setMute

        public final void setMute​(boolean value)
        设置值为 muteProperty() 。
        参数
        value - mute设置

      • isMute

        public final boolean isMute​()
        检索 muteProperty()值。
        结果
        静音设置

      • muteProperty

        public BooleanProperty muteProperty​()
        播放器音频是否静音 值true表示音频未生成。 该属性的值对volume没有影响，即如果音频静音，然后解除静音，音频播放将恢复到相同的声音级别，当然volume属性没有被修改。 默认值为false 。
        另请参见：
        isMute() ， setMute(boolean)

      • setOnMarker

        public final void setOnMarker​(EventHandler<MediaMarkerEvent> onMarker)
        设置标记事件处理程序。
        参数
        onMarker - 标记事件处理程序。

      • getOnMarker

        public final EventHandler<MediaMarkerEvent> getOnMarker​()
        检索标记事件处理程序。
        结果
        标记事件处理程序。

      • setOnEndOfMedia

        public final void setOnEndOfMedia​(Runnable value)
        设置媒体事件处理程序的结束。
        参数
        value - 事件处理程序或 null 。

      • getOnEndOfMedia

        public final Runnable getOnEndOfMedia​()
        检索媒体事件处理程序的结束。
        结果
        事件处理程序或 null 。

      • setOnReady

        public final void setOnReady​(Runnable value)
        设置 MediaPlayer.Status.READY事件处理程序。
        参数
        value - 事件处理程序或 null 。

      • setOnPaused

        public final void setOnPaused​(Runnable value)
        设置 MediaPlayer.Status.PAUSED事件处理程序。
        参数
        value - 事件处理程序或 null 。

      • setOnHalted

        public final void setOnHalted​(Runnable value)
        设置 MediaPlayer.Status.HALTED事件处理程序。
        参数
        value - 事件处理程序或 null 。

      • setOnRepeat

        public final void setOnRepeat​(Runnable value)
        设置重复事件处理程序。
        参数
        value - 事件处理程序或 null 。

      • getOnRepeat

        public final Runnable getOnRepeat​()
        检索重复事件处理程序。
        结果
        事件处理程序或 null 。

      • setAudioSpectrumNumBands

        public final void setAudioSpectrumNumBands​(int value)
        设置音频频谱中的频带数。
        参数
        value - 光谱带数; value必须是¥2

      • getAudioSpectrumNumBands

        public final int getAudioSpectrumNumBands​()
        检索音频频谱中的频带数。
        结果
        光谱带的数量。

      • audioSpectrumNumBandsProperty

        public IntegerProperty audioSpectrumNumBandsProperty​()
        音频频谱中的频带数。 默认值为128; 最小值为2.音频信号的频率范围将分为指定数量的频率仓。 例如，典型的数字音乐信号的频率范围为[0.0, 22050] 。 如果在这种情况下光谱带的数量设置为10，则频谱中每个频率仓的宽度将为2205 ，最低频率仓的下限等于0.0 。
        另请参见：
        getAudioSpectrumNumBands() ， setAudioSpectrumNumBands(int)

      • setAudioSpectrumInterval

        public final void setAudioSpectrumInterval​(double value)
        设置音频频谱通知间隔的值，单位为秒。
        参数
        value - 指定频谱更新间隔的正值

      • getAudioSpectrumInterval

        public final double getAudioSpectrumInterval​()
        检索音频频谱通知间隔的值，单位为秒。
        结果
        光谱更新间隔

      • setAudioSpectrumThreshold

        public final void setAudioSpectrumThreshold​(int value)
        以分贝设置音频频谱阈值。
        参数
        value - 以dB为单位的频谱阈值; 必须是0 。

      • getAudioSpectrumThreshold

        public final int getAudioSpectrumThreshold​()
        以分贝取回音频频谱阈值。
        结果
        光谱阈值以dB为单位

      • setAudioSpectrumListener

        public final void setAudioSpectrumListener​(AudioSpectrumListener listener)
        设置音频频谱的听众。
        参数
        listener - 频谱侦听器或 null 。

      • getAudioSpectrumListener

        public final AudioSpectrumListener getAudioSpectrumListener​()
        检索音频频谱的听众。
        结果
        光谱侦听器或 null

      • audioSpectrumListenerProperty

        public ObjectProperty<AudioSpectrumListener> audioSpectrumListenerProperty​()
        用于音频频谱更新的监听器。 当听众注册时，音频频谱计算被启用; 删除侦听器后，计算被禁用。 只有一个监听器可能被注册，所以如果需要多个观察者，则必须转发事件。

        例如， AudioSpectrumListener可能是有用的，例如绘制正在播放的音频的频谱或产生音乐可视化器的波形。

        另请参见：
        getAudioSpectrumListener() ， setAudioSpectrumListener(AudioSpectrumListener)

      • dispose

        public void dispose​()
        释放与播放器相关的所有资源。 调用此函数后不要使用播放器。 此方法完成后，播放器将转换为MediaPlayer.Status.DISPOSED 。 该方法可以随时调用和关于当前播放器的状态。
        从以下版本开始：
        JavaFX 8.0