org.jitsi.service.neomedia.MediaService Maven / Gradle / Ivy
/*
* Copyright @ 2015 Atlassian Pty Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jitsi.service.neomedia;
import java.beans.*;
import java.io.*;
import java.util.*;
import org.jitsi.service.neomedia.codec.*;
import org.jitsi.service.neomedia.device.*;
import org.jitsi.service.neomedia.format.*;
import org.jitsi.service.neomedia.recording.*;
import org.jitsi.utils.*;
/**
* The MediaService service is meant to be a wrapper of media libraries
* such as JMF, FMJ, FFMPEG, and/or others. It takes care of all media play and
* capture as well as media transport (e.g. over RTP).
*
* @author Emil Ivov
* @author Lyubomir Marinov
*/
public interface MediaService
{
/**
* The name of the property of MediaService the value of which
* corresponds to the value returned by
* {@link #getDefaultDevice(MediaType, MediaUseCase)}. The oldValue
* and the newValue of the fired PropertyChangeEvent are
* not to be relied on and instead a call to getDefaultDevice is to
* be performed to retrieve the new value.
*/
public static final String DEFAULT_DEVICE = "defaultDevice";
/**
* The name of the property which controls whether the libjitsi codecs
* which depend on ffmpeg (currently mp3, h264 and amrwb) will be enabled.
*/
public static final String ENABLE_FFMPEG_CODECS_PNAME
= MediaService.class.getName() + ".ENABLE_FFMPEG_CODECS";
/**
* The name of the property which controls whether the h264 formats
* will be registered in libjitsi even if the ffmpeg codec is missing.
*/
public static final String ENABLE_H264_FORMAT_PNAME
= MediaService.class.getName() + ".ENABLE_H264_FORMAT";
/**
* Adds a PropertyChangeListener to be notified about changes in
* the values of the properties of this instance.
*
* @param listener the PropertyChangeListener to be notified about
* changes in the values of the properties of this instance
*/
public void addPropertyChangeListener(PropertyChangeListener listener);
/**
* Those interested in Recorder events add listener through MediaService.
* This way they don't need to have access to the Recorder instance.
* Adds a new Recorder.Listener to the list of listeners
* interested in notifications from a Recorder.
*
* @param listener the new Recorder.Listener to be added to the
* list of listeners interested in notifications from Recorders.
*/
public void addRecorderListener(Recorder.Listener listener);
/**
* Returns a new EncodingConfiguration instance.
*
* @return a new EncodingConfiguration instance.
*/
public EncodingConfiguration createEmptyEncodingConfiguration();
/**
* Create a MediaStream which will use a specific
* MediaDevice for capture and playback of media. The new instance
* will not have a StreamConnector at the time of its construction
* and a StreamConnector will be specified later on in order to
* enable the new instance to send and receive media.
*
* @param device the MediaDevice to be used by the new instance for
* capture and playback of media
* @return a newly-created MediaStream which will use the specified
* device for capture and playback of media
*/
public MediaStream createMediaStream(MediaDevice device);
/**
* Initializes a new MediaStream of a specific MediaType.
* The new instance will not have a MediaDevice at the time of its
* initialization and a MediaDevice may be specified later on with
* the constraint that {@link MediaDevice#getMediaType()} equals
* mediaType.
*
* @param mediaType the MediaType of the new instance to be
* initialized
* @return a new MediaStream instance of the specified
* mediaType
*/
public MediaStream createMediaStream(MediaType mediaType);
/**
* Creates a MediaStream that will be using the specified
* MediaDevice for both capture and playback of media exchanged
* via the specified StreamConnector.
*
* @param connector the StreamConnector the stream should use for
* sending and receiving media or null if the stream is to not have
* a StreamConnector configured at initialization time and a
* StreamConnector is to be specified later on
* @param device the device to be used for both capture and playback of
* media exchanged via the specified StreamConnector
*
* @return the newly created MediaStream.
*/
public MediaStream createMediaStream(
StreamConnector connector,
MediaDevice device);
/**
* Initializes a new MediaStream instance which is to exchange
* media of a specific MediaType via a specific
* StreamConnector.
*
* @param connector the StreamConnector the stream should use for
* sending and receiving media or null if the stream is to not have
* a StreamConnector configured at initialization time and a
* StreamConnector is to be specified later on
* @param mediaType the MediaType of the media to be exchanged by
* the new instance via the specified connector
* @return a new MediaStream instance which is to exchange media of
* the specified mediaType via the specified connector
*/
public MediaStream createMediaStream(
StreamConnector connector,
MediaType mediaType);
/**
* Creates a MediaStream that will be using the specified
* MediaDevice for both capture and playback of media exchanged
* via the specified StreamConnector.
*
* @param connector the StreamConnector the stream should use for
* sending and receiving media or null if the stream is to not have
* a StreamConnector configured at initialization time and a
* StreamConnector is to be specified later on
* @param device the device to be used for both capture and playback of
* media exchanged via the specified StreamConnector
* @param srtpControl a control which is already created, used to control
* the ZRTP operations.
*
* @return the newly created MediaStream.
*/
public MediaStream createMediaStream(
StreamConnector connector,
MediaDevice device,
SrtpControl srtpControl);
/**
* Initializes a new MediaStream instance which is to exchange
* media of a specific MediaType via a specific
* StreamConnector. The security of the media exchange is to be
* controlled by a specific SrtpControl.
*
* @param connector the StreamConnector the stream should use for
* sending and receiving media or null if the stream is to not have
* a StreamConnector configured at initialization time and a
* StreamConnector is to be specified later on
* @param mediaType the MediaType of the media to be exchanged by
* the new instance via the specified connector
* @param srtpControl the SrtpControl to control the security of
* the media exchange
* @return a new MediaStream instance which is to exchange media of
* the specified mediaType via the specified connector
*/
public MediaStream createMediaStream(
StreamConnector connector,
MediaType mediaType,
SrtpControl srtpControl);
/**
* Creates a new MediaDevice which uses a specific
* MediaDevice to capture and play back media and performs mixing
* of the captured media and the media played back by any other users of the
* returned MediaDevice. For the AUDIO MediaType,
* the returned device is commonly referred to as an audio mixer. The
* MediaType of the returned MediaDevice is the same as
* the MediaType of the specified device.
*
* @param device the MediaDevice which is to be used by the
* returned MediaDevice to actually capture and play back media
* @return a new MediaDevice instance which uses device to
* capture and play back media and performs mixing of the captured media and
* the media played back by any other users of the returned
* MediaDevice instance
*/
public MediaDevice createMixer(MediaDevice device);
/**
* Creates a new Recorder instance that can be used to record a
* call which captures and plays back media using a specific
* MediaDevice.
*
* @param device the MediaDevice which is used for media capture
* and playback by the call to be recorded
* @return a new Recorder instance that can be used to record a
* call which captures and plays back media using the specified
* MediaDevice
*/
public Recorder createRecorder(MediaDevice device);
/**
* Creates a new Recorder instance that can be used to record media
* from a specific RTPTranslator.
* @param translator the RTPTranslator for which to create a
* Recorder
* @return a new Recorder instance that can be used to record media
* from a specific RTPTranslator.
*/
public Recorder createRecorder(RTPTranslator translator);
/**
* Initializes a new RTPTranslator which is to forward RTP and RTCP
* traffic between multiple MediaStreams.
*
* @return a new RTPTranslator which is to forward RTP and RTCP
* traffic between multiple MediaStreams
*/
public RTPTranslator createRTPTranslator();
/**
* Initializes a new SrtpControl instance with a specific
* SrtpControlType.
*
* @param srtpControlType the SrtpControlType of the new instance
* @return a new SrtpControl instance with the specified
* srtpControlType
*/
public SrtpControl createSrtpControl(SrtpControlType srtpControlType);
/**
* Get available ScreenDevices.
*
* @return screens
*/
public List getAvailableScreenDevices();
/**
* Returns the current EncodingConfiguration instance.
*
* @return the current EncodingConfiguration instance.
*/
public EncodingConfiguration getCurrentEncodingConfiguration();
/**
* Returns the default MediaDevice for the specified media
* type.
*
* @param mediaType a MediaType value indicating the kind of device
* that we are trying to obtain.
* @param useCase MediaUseCase value indicating for the use-case of
* device that we are trying to obtain.
*
* @return the currently default MediaDevice for the specified
* MediaType, or null if no such device exists.
*/
public MediaDevice getDefaultDevice(
MediaType mediaType,
MediaUseCase useCase);
/**
* Get default ScreenDevice device.
*
* @return default screen device
*/
public ScreenDevice getDefaultScreenDevice();
/**
* Returns a list containing all devices known to this service
* implementation and handling the specified MediaType.
*
* @param mediaType the media type (i.e. AUDIO or VIDEO) that we'd like
* to obtain the device list for.
* @param useCase MediaUseCase value indicating for the use-case of
* device that we are trying to obtain.
*
* @return the list of MediaDevices currently known to handle the
* specified mediaType.
*/
public List getDevices(MediaType mediaType,
MediaUseCase useCase);
/**
* Returns a {@link Map} that binds indicates whatever preferences the
* media service implementation may have for the RTP payload type numbers
* that get dynamically assigned to {@link MediaFormat}s with no static
* payload type. The method is useful for formats such as "telephone-event"
* for example that is statically assigned the 101 payload type by some
* legacy systems. Signalling protocol implementations such as SIP and XMPP
* should make sure that, whenever this is possible, they assign to formats
* the dynamic payload type returned in this {@link Map}.
*
* @return a {@link Map} binding some formats to a preferred dynamic RTP
* payload type number.
*/
public Map getDynamicPayloadTypePreferences();
/**
* Gets the MediaFormatFactory through which MediaFormat
* instances may be created for the purposes of working with the
* MediaStreams created by this MediaService.
*
* @return the MediaFormatFactory through which
* MediaFormat instances may be created for the purposes of working
* with the MediaStreams created by this MediaService
*/
public MediaFormatFactory getFormatFactory();
/**
* Gets the VolumeControl which controls the volume level of audio
* input/capture.
*
* @return the VolumeControl which controls the volume level of
* audio input/capture
*/
public VolumeControl getInputVolumeControl();
/**
* Get a MediaDevice for a part of desktop streaming/sharing.
*
* @param width width of the part
* @param height height of the part
* @param x origin of the x coordinate (relative to the full desktop)
* @param y origin of the y coordinate (relative to the full desktop)
* @return MediaDevice representing the part of desktop or null
* if problem
*/
public MediaDevice getMediaDeviceForPartialDesktopStreaming(
int width, int height, int x, int y);
/**
* Get origin for desktop streaming device.
*
* @param mediaDevice media device
* @return origin
*/
public java.awt.Point getOriginForDesktopStreamingDevice(
MediaDevice mediaDevice);
/**
* Gets the VolumeControl which controls the volume level of audio
* output/playback.
*
* @return the VolumeControl which controls the volume level of
* audio output/playback
*/
public VolumeControl getOutputVolumeControl();
/**
* Gives access to currently registered Recorder.Listeners.
* @return currently registered Recorder.Listeners.
*/
public Iterator getRecorderListeners();
/**
* Creates a preview component for the specified device(video device) used
* to show video preview from it.
*
* @param device the video device
* @param preferredWidth the width we prefer for the component
* @param preferredHeight the height we prefer for the component
* @return the preview component.
*/
public Object getVideoPreviewComponent(
MediaDevice device, int preferredWidth, int preferredHeight);
/**
* If the MediaDevice corresponds to partial desktop streaming
* device.
*
* @param mediaDevice MediaDevice
* @return true if MediaDevice is a partial desktop streaming
* device, false otherwise
*/
public boolean isPartialStreaming(MediaDevice mediaDevice);
/**
* Removes a PropertyChangeListener to no longer be notified about
* changes in the values of the properties of this instance.
*
* @param listener the PropertyChangeListener to no longer be
* notified about changes in the values of the properties of this instance
*/
public void removePropertyChangeListener(PropertyChangeListener listener);
/**
* Removes an existing Recorder.Listener from the list of listeners
* interested in notifications from Recorders.
*
* @param listener the existing Listener to be removed from the
* list of listeners interested in notifications from Recorders
*/
public void removeRecorderListener(Recorder.Listener listener);
/**
* Returns the value which will be used for the canonical end-point
* identifier (CNAME) in RTCP packets sent by this running instance of
* libjitsi.
* @return the value which will be used for the canonical end-point
* identifier (CNAME) in RTCP packets sent by this running instance of
* libjitsi.
*/
public String getRtpCname();
/**
* Creates a RecorderEventHandler instance that saves received
* events in JSON format.
* @param filename the filename into which the created
* RecorderEventHandler will save received events.
* @return a RecorderEventHandler instance that saves received
* events in JSON format.
* @throws IOException if a RecorderEventHandler could not be
* created for filename.
*/
public RecorderEventHandler createRecorderEventHandlerJson(String filename)
throws IOException;
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy