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.core;
021
022import com.avpkit.core.IAudioSamples;
023import com.avpkit.core.ICodec;
024import com.avpkit.core.IContainerFormat;
025import com.avpkit.core.IPixelFormat;
026import com.avpkit.core.IRational;
027import com.avpkit.core.ITimeValue;
028
029/**
030 * This class contains meta-information about simple media files.
031 *
032 * A simple media file is defined as a file with at most one
033 * video and at most one audio stream, and no other streams.
034 * 
035 * This is useful or objects that want to contain all the
036 * interesting data about a media file in one handy dandy
037 * object.
038 * 
039 * @author aclarke
040 */
041
042public interface ISimpleMediaFile
043{
044
045  /**
046   * Set the audio bitrate
047   * @param bitRate bitrate to use
048   */
049  public void setAudioBitRate(int bitRate);
050  
051  /**
052   * Get the audio bit rate
053   * 
054   * @return bit rate, in Hz.
055   */
056  public int getAudioBitRate();
057  
058  /**
059   * Set the number of audio channels.
060   * 
061   * @param numChannels Number of channels; only 1 or 2 supported
062   */
063  public void setAudioChannels(int numChannels);
064  
065  /**
066   * Get the number of audio channels
067   * 
068   * @return number of audio channels
069   */
070  public int getAudioChannels();
071  
072  /**
073   * Set the audio sample rate
074   * 
075   * @param sampleRate Audio sample rate in Hz (e.g. 22050)
076   */
077  public void setAudioSampleRate(int sampleRate);
078
079  /**
080   * Get the audio sample rate.
081   * 
082   * @return sample rate, in Hz.
083   */
084  public int getAudioSampleRate();
085  
086  /**
087   * Set the audio sample format you want to use in this file.
088   * @param format The sample format to use.
089   */
090  public void setAudioSampleFormat(IAudioSamples.Format format);
091  
092  /**
093   * Get the audio sample format.
094   * @return The audio sample format.  Defaults to {@link IAudioSamples.Format#FMT_S16}
095   *   if not specified.
096   */
097  public IAudioSamples.Format getAudioSampleFormat();
098  
099  /**
100   * Set the audio codec to use.
101   * 
102   * @param audioCodec The audio codec to use; if null, a user may
103   *   guess the codec from other information.
104   */
105  public void setAudioCodec(ICodec.ID audioCodec);
106  
107  /**
108   * Get the audio codec set on this configuration object.
109   * 
110   * @return The audiocodec.   if null, a user may
111   *   guess the codec from other information.
112   */
113  public ICodec.ID getAudioCodec();
114  
115  /**
116   * Set the width of the video frames in broadcasted packets
117   * @param width width in pixels
118   */
119  public void setVideoWidth(int width);
120  
121  /**
122   * Get the video width of video frames broadcasted
123   * @return width in pixels
124   */
125  public int getVideoWidth();
126
127  /**
128   * Set the height of the video frames in broadcasted packets
129   * @param height height in pixels
130   */
131  public void setVideoHeight(int height);
132
133  /**
134   * Get the video height of video frames broadcasted
135   * @return height in pixels
136   */
137  public int getVideoHeight();
138  
139  /**
140   * Set the timebase that we encode video for.
141   *
142   * @param bitRate The bitrate to use for encoding video
143   */
144  public void setVideoBitRate(int bitRate);
145
146  /**
147   * Get the video bit rate
148   * @return video bit rate
149   */
150  public int getVideoBitRate();
151
152  /**
153   * Set the TimeBase that video packets are encoded with.
154   * @param timeBase The timebase to use with this configuration, or null if unknowbn.
155   */
156  public void setVideoTimeBase(IRational timeBase);
157  
158  /**
159   * Get the timebase that packets should be encoded with.
160   * @return The timebase or null if unknown.
161   */
162  public IRational getVideoTimeBase();
163  /**
164   * Set the video codec that packets are encoded with.
165   * @param videoCodec video codec that packets are encoded with.
166   */
167  public void setVideoCodec(ICodec.ID videoCodec);
168  
169  /**
170   * Get the video codec that packets are encoded with.
171   * @return the video codec
172   */
173  public ICodec.ID getVideoCodec();
174
175  /**
176   * Return the pixel format to use
177   * @return The pixel format.
178   */
179  public IPixelFormat.Type getVideoPixelFormat();
180
181  /**
182   * Sets the pixel format to use
183   * @param aPixelFormat Pixel format
184   */
185  void setVideoPixelFormat(IPixelFormat.Type aPixelFormat);
186
187
188  /**
189   * Set the MPEG2 Num Pictures In Group Of Pictures (GOPS) settings
190   * @param gops Set the GOPS
191   */
192  public void setVideoNumPicturesInGroupOfPictures(int gops);
193  
194  /**
195   * Get the GOPS.
196   * @see #setVideoNumPicturesInGroupOfPictures(int)
197   * @return The GOPS
198   */
199  public int getVideoNumPicturesInGroupOfPictures();
200  
201  /**
202   * Set the Video Frame Rate as a rational.
203   * @param frameRate  The frame rate (e.g. 15/1), or null if unknown.
204   */
205  public void setVideoFrameRate(IRational frameRate);
206  
207  /**
208   * Get the Video Frame Rate
209   * @see #setVideoFrameRate(IRational)
210   * @return The video frame rate, or null if unknown
211   */
212  public IRational getVideoFrameRate();
213  
214  /**
215   * Set the default quality quality setting for video.  0 is highest
216   * quality.  > 0 is decreasing quality.
217   * @param quality  The quality to use.
218   */
219  public void setVideoGlobalQuality(int quality);
220  
221  /**
222   * Get the VideoGlobalQuality setting.
223   * @see #setVideoGlobalQuality(int)
224   * @return The global quality for video
225   */
226  public int getVideoGlobalQuality();
227  
228  /**
229   * Set whether you want the output stream to have video
230   * @param hasVideo Whether you want the output stream to have video
231   */
232  public void setHasVideo(boolean hasVideo);
233  
234  /**
235   * Tells whether or not the output stream should have video
236   * @return Should the output stream have video?
237   */
238  public boolean hasVideo();
239
240  /**
241   * Set whether you want the output stream to have audio
242   * @param hasAudio Whether you want the output stream to have audio
243   */
244  public void setHasAudio(boolean hasAudio);
245  
246  /**
247  * Tells whether or not the output stream should have audio
248  * @return Should the output stream have audio?
249  */
250  public boolean hasAudio();
251
252  /**
253   * Sets the container format for this stream
254   * @param format The container format
255   */
256  public void setContainerFormat(IContainerFormat format);
257  
258  /**
259   * Get the container format, if known, for this container.
260   * @return The container format
261   */
262  public IContainerFormat getContainerFormat();
263
264  /**
265   * is the audio bit rate known?
266   * @return the audioBitRateKnown
267   */
268  public boolean isAudioBitRateKnown();
269  
270  /**
271   * set if the audio channels are known
272   * @param audioChannelsKnown the audioChannelsKnown to set
273   */
274  public void setAudioChannelsKnown(boolean audioChannelsKnown);
275
276  /**
277   * are the # of audio channels known?
278   * @return the audioChannelsKnown
279   */
280  public boolean isAudioChannelsKnown();
281
282  /**
283   * set if the audio sample rate is known.
284   * @param audioSampleRateKnown the audioSampleRateKnown to set
285   */
286  public void setAudioSampleRateKnown(boolean audioSampleRateKnown);
287
288  /**
289   * is the audio sample rate known?
290   * @return the audioSampleRateKnown
291   */
292  public boolean isAudioSampleRateKnown();
293
294  /**
295   * set if the video height is known.
296   * @param videoHeightKnown the videoHeightKnown to set
297   */
298  public void setVideoHeightKnown(boolean videoHeightKnown);
299
300  /**
301   * is the video height known?
302   * @return the videoHeightKnown
303   */
304  public boolean isVideoHeightKnown();
305
306  /**
307   * set if the video width is known.
308   * @param videoWidthKnown the videoWidthKnown to set
309   */
310  public void setVideoWidthKnown(boolean videoWidthKnown);
311
312  /**
313   * is the video width known?
314   * @return the videoWidthKnown
315   */
316  public boolean isVideoWidthKnown();
317
318  /**
319   * set if the video bit rate is known.
320   * @param videoBitRateKnown the videoBitRateKnown to set
321   */
322  public void setVideoBitRateKnown(boolean videoBitRateKnown);
323
324  /**
325   * is the video bit rate known?
326   * @return the videoBitRateKnown
327   */
328  public boolean isVideoBitRateKnown();
329
330  /**
331   * set if the MPEG number of pictures in a group of pictures is known?
332   * @param videoGOPSKnown the videoGOPSKnown to set
333   */
334  public void setVideoNumPicturesInGroupOfPicturesKnown(boolean videoGOPSKnown);
335
336  /**
337   * is the MPEG number of pictures in a group of pictures known?
338   * @return the videoGOPSKnown
339   */
340  public boolean isVideoNumPicturesInGroupOfPicturesKnown();
341
342  /**
343   * set if the global quality setting is known.
344   * @param videoGlobalQualityKnown the videoGlobalQualityKnown to set
345   */
346  public void setVideoGlobalQualityKnown(boolean videoGlobalQualityKnown);
347
348  /**
349   * is the global quality setting known?
350   * @return the videoGlobalQualityKnown
351   */
352  public boolean isVideoGlobalQualityKnown();
353
354  /**
355   * set if the video pixel format is known.
356   * @param videoPixelFormatKnown the videoPixelFormatKnown to set
357   */
358  public void setVideoPixelFormatKnown(boolean videoPixelFormatKnown);
359
360  /**
361   * is the video pixel format known?
362   * @return the videoPixelFormatKnown
363   */
364  public boolean isVideoPixelFormatKnown();
365
366  /**
367   * Set the time base to use when encoding or decoding audio
368   * @param aTimeBase The timebase to use, or null if unknown.
369   */
370  public void setAudioTimeBase(IRational aTimeBase);
371  
372  /**
373   * Get the time base used when encoding or decoding audio.
374   * @return the timebase, or null if unknown.
375   */
376  public IRational getAudioTimeBase();
377
378  /**
379   * Set the duration that we'll assume for the stream we're representing.
380   * 
381   * @param duration the duration to assume for this file.  null means unknown.
382   */
383  void setDuration(ITimeValue duration);
384
385  /**
386   * Get the duration that we'll assume for the stream we're representing.
387   * @return the duration, or null if unknown.
388   */
389  ITimeValue getDuration();
390
391  /**
392   * set if the audio bit rate is known.
393   * @param audioBitRateKnown the audioBitRateKnown to set
394   */
395  void setAudioBitRateKnown(boolean audioBitRateKnown);
396
397  /**
398   * Set the URL that this stream contains info for.
399   * @param aUrl The url, including protocol string, or null if unknown.
400   */
401  void setURL(String aUrl);
402
403  /**
404   * Return the URL for this stream.
405   * @return The URL, or null if unknown.
406   */
407  String getURL();
408}