org.jmythapi.protocol
Interface IRemoteEncoder

All Superinterfaces:

IVersionable

All Known Implementing Classes:

RemoteEncoder

public interface IRemoteEncoder
extends IVersionable

This interface represents a special view to a MythTV-recorder. It is mainly used to query and control the recording state of a recorder.

Supported Protocol Versions:

Protocol Version Ranges:
All listed functions are supported by at least one of the supported protocol-versions. If a given function is not supported by all known protocol-versions, it is marked with the MythProtoVersion annotation. Additionally the lower bound of the version range is documented with the @since javadoc tag, whereas the upper bound is documented with the @deprecated tag.

Extended Version Ranges:
Please note that many functions are usable (maybe with some restrictions) beyond the given protocol range, if an alternative set of functions can be used to achieve the same result. If such an "extended" version-range is available for a function, this is mentioned as "fallback-from"- and "fallback-to"-version in the functions javadoc.

Supported Versions:
Which protocol versions are in general supported by the jMythAPI can be seen in the enumeration ProtocolVersion.

How to start:

Connect to the recorder:
The following steps are required to connect to an encoder:

1. Establish a connection to the backend and register as a client:
   IBackend backend = BackendFactory.createBackend(...);
backend.connect();
backend.annotatePlayback(...);
2. Connect to a recorder:
   IRecorderInfo recorderInfo = backend.getNextFreeRecorder(); or
   IRecorderInfo recorderInfo = backend.getRecorderForNum(Integer); or
   IRecorderInfo recorderInfo = backend.getRecorderForProgram(IProgramInfo);
3. Get the encoder:
   IRemoteEncoder encoder = recorder.getRemoteEncoder();

Use the encoder:
Afterwards you can use any function provided by this interface to query and control your encoder.
See the usage examples for some examples.

Disconnect from the encoder:
This is not required, because an encoder shares a connection with its recorder.

Usage Examples:

    // the connected backend
    IBackend backend = ...;

    // get a specific recorder
    IRecorderInfo recorderInfo = backend.getRecorderForNum(1);
    if(recorderInfo != null) {
        // connect to the recorder
        IRecorder recorder = backend.getRecorder(recorderInfo);
        
        // query the current recording state
        if(recorder.isRecording()) {
            // getting a reference to the encoder
            IRemoteEncoder encoder = recorder.getRemoteEncoder();
            
            // check the encoder state
            IRemoteEncoderState encoderState = encoder.getState();
            System.out.println(String.format("The encoder is in state '%s'.",encoderState.getState()));
        }
        
        // close recorder connection
        recorder.close();
    }
 

More usage Examples:

See the javadoc for the methods provided by this interface.

• Work with recordings:
  • Start a recording (link)
  • Stop a recording (link)
  • Cancel next recording (link)
  • Check if recording is in progress (link)
  • Get current recording (link)
• Work with inputs:
  • Get currently used input (link)
  • Get free inputs (link)
  • Get all inputs (link)
• Query Encoder status:
  • Query busy status (link)
  • Query sleep status (link)
  • Query recording status (link)
  • Query current state (link)
  • Query encoder flags (link)
  • Query encoder bitrate (link)

See Also:

getRemoteEncoder

Method Summary

boolean	cancelNextRecording(Boolean cancel) Tells the encoder to cancel the next recording.
IInputInfoTuned	getBusyInput() Queries the currently used input of a busy encoder.
IInputInfoTuned	getBusyInput(Integer timeBuffer) Queries the input that will be used by the encoder in the given amount of seconds.
IRemoteEncoderBusyStatus	getBusyStatus() Query the current busy status of the recorder.
IRemoteEncoderBusyStatus	getBusyStatus(Integer timeBuffer) Query the current busy status of the recorder.
IProgramInfo	getCurrentRecording() Returns the encoders current recording.
IRemoteEncoderFlags	getFlags() Gets additional information about the current encoder state.
IFreeInputList	getFreeInputs() Gets the free inputs of the encoder.
List<IInputInfo>	getInputs() Gets a list of all inputs of the encoder.
long	getMaxBitrate() Gets the maximum bitrate the encoder can output.
IProgramRecordingStatus	getRecordingStatus() Gets the current recording status of the tuner.
int	getRemoteEncoderID() Gets the ID of this remote encoder.
ISleepStatus	getSleepStatus() Gets the current sleep status of the encoder.
IRemoteEncoderState	getState() Returns the current encoder state (TvState).
boolean	isBusy() Query whether the recorder is currently busy.
boolean	isBusy(Integer timeBuffer) Query whether the recorder is busy, or will be within the next time_buffer seconds.
boolean	matchesRecording(IProgramInfo programInfo) Checks if this encoder is currently recording the given recording.
boolean	startRecording(IProgramInfo programInfo) TODO: is it possible to pass in a Nextrecorderproiinfo here?
boolean	stopRecording() Stop a currently active recording on the given recorder.

Methods inherited from interface org.jmythapi.IVersionable

getVersionNr

Method Detail

getRemoteEncoderID

int getRemoteEncoderID()

Gets the ID of this remote encoder.

Returns:

the remote encoder ID.

getMaxBitrate

long getMaxBitrate()
                   throws IOException

Gets the maximum bitrate the encoder can output.

Throws:

IOException - on communication errors

Since:

17

See Also:

QUERY_REMOTEENCODER_GET_MAX_BITRATE

MythTV protocol range: [17,-1)

	Version	Date	Additional Version Info
Added	17	2005-05-24	Changelog, SVN-Rev.: 6482
Removed	-1

getSleepStatus

ISleepStatus getSleepStatus()
                            throws IOException

Gets the current sleep status of the encoder.

Returns:

the current sleep status of the encoder.

Throws:

IOException - on communication errors.

Since:

45

See Also:

QUERY_REMOTEENCODER_GET_SLEEPSTATUS

MythTV protocol range: [45,-1)

	Version	Date	Additional Version Info
Added	45	2009-05-09	Changelog, SVN-Rev.: 20523
Removed	-1

getState

IRemoteEncoderState getState()
                             throws IOException

Returns the current encoder state (TvState).

For example an idle encoder is in the state NONE, whereas a encoder recording a scheduled program is in the state RECORDING_ONLY.

See State for all available states.

Returns:

the remote-encoder state

Throws:

IOException - on communication errors.

Since:

00

See Also:

QUERY_REMOTEENCODER_GET_STATE

MythTV protocol range: [00,-1)

	Version	Date	Additional Version Info
Added	00
Removed	-1

getFlags

IRemoteEncoderFlags getFlags()
                             throws IOException

Gets additional information about the current encoder state.

In addition to the encoder-state, various other flags can be checked to get further information.
For example an idle encoder may currently fetch EIT informations (See EIT_SCANNER_RUNNING).

See Flags for all available flags.

Returns:

additional information about the current encoder state.

Throws:

IOException - on communication errors.

Since:

37

See Also:

QUERY_REMOTEENCODER_GET_FLAGS

MythTV protocol range: [37,-1)

	Version	Date	Additional Version Info
Added	37	2008-01-14	Changelog, SVN-Rev.: 15437
Removed	-1

isBusy

boolean isBusy()
               throws IOException

Query whether the recorder is currently busy.

Returns:

true if the encoder is currently busy.

Throws:

IOException - on communication errors.

Since:

00

See Also:

isBusy(Integer)

MythTV protocol range: [00,-1)

	Version	Date	Additional Version Info
Added	00
Removed	-1

isBusy

boolean isBusy(Integer timeBuffer)
               throws IOException

Query whether the recorder is busy, or will be within the next time_buffer seconds.

Returns:

true if the encoder is currently busy or will be busy in the given amount of seconds.

Throws:

IOException - on communication errors.

Since:

00

See Also:

getBusyStatus(Integer)

MythTV protocol range: [00,-1)

	Version	Date	Additional Version Info
Added	00
Removed	-1

getBusyStatus

IRemoteEncoderBusyStatus getBusyStatus()
                                       throws IOException

Query the current busy status of the recorder.

If the encoder is busy the response includes informations about the busy encoder input device (since 37).

Returns:

the current busy status, including informations about the busy input device.

Throws:

IOException

Since:

00

See Also:

getBusyStatus(Integer), QUERY_REMOTEENCODER_IS_BUSY

MythTV protocol range: [00,-1)

	Version	Date	Additional Version Info
Added	00
Changed	37	2008-01-14	Changelog, SVN-Rev.: 15437
Removed	-1

getBusyStatus

IRemoteEncoderBusyStatus getBusyStatus(Integer timeBuffer)
                                       throws IOException

Query the current busy status of the recorder.

Parameters:

timeBuffer - in seconds (Since 37)

Throws:

IOException - on communication errors.

Since:

00

See Also:

QUERY_REMOTEENCODER_IS_BUSY

MythTV protocol range: [00,-1)

	Version	Date	Additional Version Info
Added	00
Changed	37	2008-01-14	Changelog, SVN-Rev.: 15437
Removed	-1

getBusyInput

IInputInfoTuned getBusyInput()
                             throws IOException

Queries the currently used input of a busy encoder.

This function internally uses getBusyStatus() to determine the current encoder status.

Returns:

the busy input or null if the encoder is not busy

Throws:

IOException - on communication errors.

Since:

37

See Also:

QUERY_REMOTEENCODER_IS_BUSY

MythTV protocol range: [37,-1)

	Version	Date	Additional Version Info
Added	37	2008-01-14	Changelog, SVN-Rev.: 15437
Removed	-1

getBusyInput

IInputInfoTuned getBusyInput(Integer timeBuffer)
                             throws IOException

Queries the input that will be used by the encoder in the given amount of seconds.

This function internally uses getBusyStatus(Integer) to determine the encoder status.

Parameters:

timeBuffer - in seconds (Since 37)

Returns:

the busy input or null if the encoder is not busy

Throws:

IOException - on communication errors.

Since:

37

See Also:

QUERY_REMOTEENCODER_IS_BUSY

MythTV protocol range: [37,-1)

	Version	Date	Additional Version Info
Added	37	2008-01-14	Changelog, SVN-Rev.: 15437
Removed	-1

getFreeInputs

IFreeInputList getFreeInputs()
                             throws IOException

Gets the free inputs of the encoder.

Returns:

a list of free inputs or null if there is no free input.

Throws:

IOException - on communication errors.

Since:

37

See Also:

QUERY_REMOTEENCODER_GET_FREE_INPUTS

MythTV protocol range: [37,-1)

	Version	Date	Additional Version Info
Added	37	2008-01-14	Changelog, SVN-Rev.: 15437
Removed	-1

getInputs

List<IInputInfo> getInputs()
                           throws IOException

Gets a list of all inputs of the encoder.

This method internally uses getFreeInputs() to determine all free inputs and getBusyInput() to get the currently used input.

Usage Example:

 IRemoteEncoder encoder = ...; // an already connected encoder
  
 List<IInputInfo> allInputs = encoder.getInputs();
 for(IInputInfo input : allInputs) {
    System.out.println(String.format(
       "Input %d (name: %s, source: %d, card: %d, multiplex: %d) is %s.",
       input.getInputID(),
       input.getInputName(),
       input.getSourceID(),
       input.getCardID(),
       input.getMultiplexID(),
       input.isBusy()?"busy":"idle"
    ));
  }
  
  

Returns:

a list of all inputs of this encoder.

Throws:

IOException - on communication errors.

Since:

37

See Also:

getFreeInputs(), getBusyInput(), QUERY_REMOTEENCODER_GET_FREE_INPUTS, QUERY_REMOTEENCODER_IS_BUSY

MythTV protocol range: [37,-1)

	Version	Date	Additional Version Info
Added	37	2008-01-14	Changelog, SVN-Rev.: 15437
Removed	-1

matchesRecording

boolean matchesRecording(IProgramInfo programInfo)
                         throws IOException

Checks if this encoder is currently recording the given recording.

Parameters:

programInfo - the recording to check.

Returns:

true if the encoder is currently recording the given program.

Throws:

IOException - on communication errors.

Since:

00

See Also:

QUERY_REMOTEENCODER_MATCHES_RECORDING, matchesRecording(IProgramInfo)

MythTV protocol range: [00,-1)

	Version	Date	Additional Version Info
Added	00
Removed	-1

startRecording

boolean startRecording(IProgramInfo programInfo)
                       throws IOException

TODO: is it possible to pass in a Nextrecorderproiinfo here?

Parameters:

programInfo - the recording to start

Returns:

true on success

Throws:

IOException - on communication errors.

Since:

00

See Also:

QUERY_REMOTEENCODER_START_RECORDING

MythTV protocol range: [00,-1)

	Version	Date	Additional Version Info
Added	00
Removed	-1

stopRecording

boolean stopRecording()
                      throws IOException

Stop a currently active recording on the given recorder.

Throws:

IOException - on communication errors.

Since:

37

See Also:

QUERY_REMOTEENCODER_STOP_RECORDING

MythTV protocol range: [37,-1)

	Version	Date	Additional Version Info
Added	37	2008-01-14	Changelog, SVN-Rev.: 15437
Removed	-1

getCurrentRecording

IProgramInfo getCurrentRecording()
                                 throws IOException

Returns the encoders current recording.

Usage Note:

According to the MythTV Player homepage the backend may crash if this function is called on an idle encoder. Therefore this function first checks via a call to isBusy() if this encoder is busy and if it is not, it just returns null.

Returns:

the current recording, or null if the encoder is currently not recording.

Throws:

IOException - on communication errors

Since:

19

See Also:

QUERY_REMOTEENCODER_GET_CURRENT_RECORDING

MythTV protocol range: [19,-1)

	Version	Date	Additional Version Info
Added	19	2005-10-09	Changelog, SVN-Rev.: 7427
Removed	-1

getRecordingStatus

IProgramRecordingStatus getRecordingStatus()
                                           throws IOException

Gets the current recording status of the tuner.

Protocol Version Hint:

If this function is called prior to protocol-version 63, this function uses getCurrentRecording() to get the current recording and calls IProgramInfo.getRecordingStatus() afterwards, to determine the current recording status. If there is no current recording, null is returned.

Returns:

the recording status or null if unknown.

Throws:

IOException - on communication errors.

Since:

63

See Also:

QUERY_REMOTEENCODER_GET_RECORDING_STATUS

MythTV protocol range: [63,-1)

	Version	Date	Additional Version Info
Added	63	2010-09-25	Changelog, MythBuntu-Release: 11.04, MythTV-Release: 0.24, SVN-Rev.: 26518
Removed	-1

cancelNextRecording

boolean cancelNextRecording(Boolean cancel)
                            throws IOException

Tells the encoder to cancel the next recording.

This is used when the user is watching "Live TV" and does not want to allow the recorder to be taken for a pending recording.

Parameters:

cancel - if the next recording should be canceled or continued.

Throws:

IOException - on communication errors

Since:

37

See Also:

QUERY_REMOTEENCODER_CANCEL_NEXT_RECORDING

MythTV protocol range: [00,-1)

	Version	Date	Additional Version Info
Added	00
Removed	-1