001/*******************************************************************************
002 * Copyright (c) 2024, 2026, Olivier Ayache.  All rights reserved.
003 *
004 * This file is part of AVPKit.
005 *
006 * AVPKit is free software: you can redistribute it and/or modify
007 * it under the terms of the GNU Lesser General Public License as published by
008 * the Free Software Foundation, either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * AVPKit is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with AVPKit.  If not, see <http://www.gnu.org/licenses/>.
018 *******************************************************************************/
019
020package com.avpkit.mediatool;
021
022import javax.sound.sampled.DataLine;
023
024/**
025 * <strong>EXPERIMENTAL ONLY</strong>: An {@link IMediaListener} that plays
026 * audio, video or both, while listening to a {@link IMediaGenerator} that
027 * produces raw media.
028 * <p>
029 * 
030 * The {@link IMediaViewer} is currently in <strong>experimental</strong> mode.
031 * That means it has some bugs where it can hang (in particular if there isn't
032 * as much audio in the file as video, but there are others), and
033 * we expect there will be some API and functionality changes in
034 * future releases. It's really something we're playing with and would like
035 * to get feedback on, but do not use it in production projects .
036 * You should not expect backwards compatibility on this
037 * part of the API.
038 * 
039 * </p>
040 * <p>
041 * 
042 * You can use this object to attach to a {@link IMediaReader} or a
043 * {@link IMediaWriter} to see the output as they work.
044 * 
045 * </p>
046 * <p>
047 * 
048 * You can optionally have the {@link IMediaViewer} display statistics on-screen
049 * while playing about the contents of the media file, and overlay a clock on
050 * the screen while playing.
051 * 
052 * </p>
053 * <p>
054 * 
055 * Please note that due to limitations in Sun's sound system on Linux there is a
056 * lag between audio and video in Linux. Not much we can do about it, but anyone
057 * who knows a fix (the issue is with the precision of
058 * {@link DataLine#getMicrosecondPosition()}), please let us know.
059 * 
060 * </p>
061 */
062
063public interface IMediaViewer extends IMediaListener
064{
065  /**
066   * The mode you want to view media in.
067   * @author aclarke
068   *
069   */
070  public enum Mode
071  {
072    /** Play audio & video streams in real-time. */
073
074    AUDIO_VIDEO(true, true, true),
075
076    /** Play only audio streams, in real-time. */
077
078    AUDIO_ONLY(true, false, true),
079
080    /** Play only video streams, in real-time. */
081
082    VIDEO_ONLY(false, true, true),
083
084    /** Play only video, as fast as possible. */
085
086    FAST_VIDEO_ONLY(false, true, false),
087
088    /** Play neither audio or video, also disables statistics. */
089
090    DISABLED(false, false, false);
091
092    // play audio
093    
094    private final boolean mPlayAudio;
095    
096    // show video
097    
098    private final boolean mShowVideo;
099
100    // show media in real time
101
102    private final boolean mRealtime;
103
104    // construct a mode
105
106    private Mode(boolean playAudio, boolean showVideo, boolean realTime)
107    {
108      mPlayAudio = playAudio;
109      mShowVideo = showVideo;
110      mRealtime = realTime;
111    }
112
113    /**
114     * Does this mode play audio?
115     * @return true if we play audio
116     */
117    public boolean playAudio()
118    {
119      return mPlayAudio;
120    }
121
122    /**
123     * Does this mode display video?
124     * @return displays video
125     */
126    public boolean showVideo()
127    {
128      return mShowVideo;
129    }
130
131    /**
132     * Does this mode play in real time or in fast time?
133     * @return true if real time
134     */
135    public boolean isRealTime()
136    {
137      return mRealtime;
138    }
139  }
140
141  /**
142   * Will this viewer show a stats window?
143   * @return will this viewer show a stats window?
144   */
145
146  public abstract boolean willShowStatsWindow();
147
148  /**
149   * Get the default close operation. The close operation speciefies
150   * what should Swing do if the window is closed.  See the {@link
151   * javax.swing.WindowConstants} documentation for valid values.
152   *
153   * @return the default close operation
154   */
155
156  public abstract int getDefaultCloseOperation();
157
158  /** Get media playback mode.
159   *
160   * @return the playback mode
161   * 
162   * @see MediaViewer.Mode
163   */
164
165  public abstract Mode getMode();
166
167}