hp.telephony.media
Interface Recorder

All Superinterfaces:

ASRConstants, CoderConstants, EchoCancellerConstants, FaxConstants, RecorderConstants, Resource, ResourceConstants, RTPRecorderConstants, SMSRecorderConstants, SpeechDetectorConstants

All Known Implementing Classes:

AsyncMediaGroup

public interface Recorder

extends Resource, RecorderConstants, ASRConstants, SpeechDetectorConstants, FaxConstants, EchoCancellerConstants, RTPRecorderConstants, SMSRecorderConstants

Defines a method for recording a media stream into a data file. A Recorder transcodes the media stream data from the telephony network, and stores the result in a Data Stream Container (MSC).

The Recorder interface is also used to send recognize requests to an ASR server (see below).

It can also be used to receive SMS-TL messages (see below).

This resource will be able to receive faxes (see below).

A variety a coder types are defined, depending on the particular Recorder.

Run Time Controls can be used to stop recording.

A Recorder may optionally support additional processing features. These features define parameters and runtime controls that affect operation of an ongoing play operation. The presence of these features is indicated by a true value for the following attributes:

Attribute:	indicates the ability to:
a_Beep	NOT SUPPORTED BY OC MP. play a beep before recording. parameters p_StartBeep, p_BeepLength, p_BeepFrequency are supported
a_FixedBeep	do limited beep. In OC MP, considered always true. parameter p_StartBeep is supported
a_CoderTypes	NOT SUPPORTED BY OC MP AS SUCH. Instead, p_CoderTypes can be set for each operation, specifying the one coder used. use the listed coders. see CoderConstants for defined coder types
a_Pause	pause and resume while recording. In OC MP, considered always true. RTC actions rtca_Pause and rtca_Resume are supported
a_SilenceTruncation	did indicate to allocate silence truncation resources NOT SUPPORTED BY OC MP AS SUCH. Instead, a Voice Activity Detector type "n" should be available in the ConfigSpec.

States:

The following is the state diagram for a recorder.

The recorder is either Idle, Active, or Paused.

record() fails unless the state is Idle. and then the state becomes Active or Paused. The state of the Recorder after play() starts is determined by the Boolean value of the parameter p_StartPaused. The state transitions to Active if p_StartPaused is false. The state transitions to Paused if p_StartPaused is true.

When recording stops, the state becomes Idle. Recording stops for a variety of reasons.

rtca_Pause has no effect unless state is Recording, and then the state becomes Paused, and ev_Pause is sent to onRecorderEvent().

rtca_Resume has no effect unless state is Paused, and then the state becomes Recording, and ev_Resume is sent to onRecorderEvent().

Note: The format of the String that identifies an MSC is not defined by this release of specification. The vendor-specific implementation of the MediaService (for example, the vendor of the server or resource) shall define the supported String formats.

For example, an implementation may support URLs or File pathnames; in which case an application could use Strings of the form: file://node/dir/name or dir/dir/name

If the MSC identifier is a file pathname, it is interpreted in the logical filename-space of the server. THIS IS OC MP's CASE. Applications and their prompts need to be installed with correct pathnames.

Speech detection operations

The following is the state diagram for a RTPRecorder associated with a speech detector (cf. speechEnabled configSpecs).

In that ConfigSpec case, both state diagrams should be taken into account.

The result of the SpeechDetector record() operation is delivered through onRecorderEvent() callback .

SpeechDetector parameters, specific RecorderEvent qualifiers & supported RTC triggers are defined in the SpeechDetectorConstants interface.

ASR Operations

Recorder interface for sending ASR recognize requests

For ASR server access, the interface remains the same, except that:

• The streamID parameter is the Audio Service in form rtsp://audioservice
• The grammar must be passed in the optArgs:
  • Directly as a String with the key p_LoadGrammar. In this case the default type is "application/grammar+xml". This can be overridden with the p_GrammarType argument if the server associated with the Audio Service supports other types of grammar.
  • As a uri to a pre-defined grammar with the key p_GrammarId (see later for how to pre-define grammars), in which case the grammar type must be set: p_GrammarType set to "text/uri-list"

The result of the ASR record() operation is delivered in an ASRRecorderEvent to the onRecorderEvent() callback of the ResourceEventListener.

If the recognition was successful, then an eventId equal to ASRConstants.ev_(Non)Final(Rule|Word)Result is received. Currently only ev_FinalRuleResult events are supported (grammar based recognizers)

If the recognition failed, then an ev_Record is received. This may have an error set (e.g. e_BadGrammar, e_ServerFailed) or if e_OK, a qualifier such as q_Standard for a no-match recognition or q_Duration for a recognition timeout or q_Silence for a noinput timeout.

Refer to ASRConstants for full details on these symbols and their meaning.

Code snippet about how using a ASR Audio Service

 // ASR AudioService
 String asrAudioService="rtsp://AsrAudioService";
 // Load grxml grammar as a string from a file or whatever (not OCMP method)
 String grammar = getGrammarFromFile("/opt/services/grammar.xml");
 
 // empty arg dictionary
 optArgs.clear();
 // pass parameters
 optArgs.put(p_LoadGrammar, grammar);
 try {
 // start recording
 mediagroup.record(asrAudioService,myRtcs,optArgs);
 } catch (Exception e) {
 // exception processing etc;
 }
 

SMS-TL Operations

Recorder interface for receiving SMS-TL messages

For SMS-TL messages receiving, the interface remains the same, except that:

• The streamID parameter is the SMS mode in form sms-tl://
• No SMS-TL optional record parameters are passed in the optArgs hashtable.

The result of the SMS record() operation is delivered in an SMSRecorderEvent to the onRecorderEvent() callback of the ResourceEventListener.

If the SMS record was successful, then an eventId equal to ev_SMS is received.

Refer to SMSRecorderConstants for full details on these symbols and their meaning.

Code snippet about how using a SMS

 // SMS
 String smsService="sms-tl://";
 
 // empty arg dictionary
 optArgs.clear();
 try {
 // start recording
 mediagroup.record(smsService,myRtcs,optArgs);
 } catch (Exception e) {
 // exception processing etc;
 }
 

Fax Operations

The target AsyncMediaGroup should be brought by loopCP with ConfigSpec.basicFaxConfig.

Recorder interface for answering the V25 fax protocol

The interface remains the same, except that:

• The streamID parameter is the 20 printable characters fax ID, prefixed by fax://
• Mandatory parameters are passed in the params hashtable to setup the local fax characteritics.

Code snippet for an incoming call receiving fax pages as one TIFF file

 params.put(FaxConstants.p_PagesEncoding         ,FaxConstants.v_TIFF);
 params.put(FaxConstants.p_StorePath             ,"/home/facsimile/"+uniqueSessionId+"/");
 params.put(FaxConstants.p_Suffix                ,".fax");
 params.put(FaxConstants.p_VerticalResolution    ,FaxConstants.v_Normal_98lpi);
 params.put(FaxConstants.p_PageWidth             ,FaxConstants.v_1728pixelsIn215mm);
 params.put(FaxConstants.p_PageLength            ,FaxConstants.v_A4_297mm);
 params.put(FaxConstants.p_PageResolution        ,FaxConstants.v_Page_Resolution_0200_0100);
 params.put(FaxConstants.p_FileType              ,FaxConstants.v_T4_1D_ModifiedHuffman);
 params.put(FaxConstants.p_FaxTimeOut            ,new Integer(900000));//15 minutes
 params.put(FaxConstants.p_MaxPageToReceive      ,new Integer(5));
 
 //   we receive an incoming call, and act as a receiving fax machine :
 params.put(FaxConstants.p_Role                  ,FaxConstants.v_Answerer);
 params.put(FaxConstants.p_CapabilityToReceive   ,Boolean.TRUE);
 
 //   we do not have any page to send, we just receive :
 params.put(FaxConstants.p_EnablePolling         ,Boolean.FALSE);
 
 //   start receiving one or more pages (/home/facsimile/pageN1.bmp, /home/facsimile/pageN2.bmp, and so forth)
 String servicePrefixPlusFaxID = FaxConstants.v_Prefix+"hp OC MP 2.4C2";
 mediagroup.record(servicePrefixPlusFaxID,myRtcs,params);
 

The result of the Fax record() operation is delivered in a FaxEvent to the onPlayerEvent() or onRecorderEvent() callback of the ResourceEventListener.

Note : the regular direct receive is delivered with 2.4C2 EA.

Code snippet for an outgoing call going to poll remote able to provide fax

 params.put(FaxConstants.p_PagesEncoding         ,FaxConstants.v_TIFF);
 params.put(FaxConstants.p_StorePath             ,"/home/facsimile/"+uniqueSessionId+"/");
 params.put(FaxConstants.p_Suffix                ,".fax");
 params.put(FaxConstants.p_VerticalResolution    ,FaxConstants.v_Normal_98lpi);
 params.put(FaxConstants.p_PageWidth             ,FaxConstants.v_1728pixelsIn215mm);
 params.put(FaxConstants.p_PageLength            ,FaxConstants.v_A4_297mm);
 params.put(FaxConstants.p_PageResolution        ,FaxConstants.v_Page_Resolution_0200_0100);
 params.put(FaxConstants.p_FileType              ,FaxConstants.v_T4_1D_ModifiedHuffman);
 params.put(FaxConstants.p_FaxTimeOut            ,new Integer(900000));//15 minutes
 params.put(FaxConstants.p_MaxPageToReceive      ,new Integer(5));
 //   parameters above are like for the regular direct receive.

 //   we receive an incoming call, and are sending :
 params.put(FaxConstants.p_Role                  ,FaxConstants.v_Caller);// as for the regular direct send
 params.put(FaxConstants.p_CapabilityToReceive   ,Boolean.TRUE);// as for the regular direct receive

 //   we do not have any page to receive, we just send :
 params.put(FaxConstants.p_EnablePolling         ,Boolean.TRUE);// unlike the regular direct receive
 

The record() method will be called the same way.

Note : the reversed polling mode is delivered within late 2.4C2.

Since:

OCMP 2.0

Field Summary

Fields inherited from interface hp.telephony.media.ResourceConstants

e_Disconnected, e_OK, FOREVER, q_Duration, q_RTC, q_Standard, q_Stop, rtcc_Disconnected, rtcc_TriggerRTC, v_Forever

Fields inherited from interface hp.telephony.media.RecorderConstants

a_Beep, a_CoderTypes, a_FixedBeep, a_Pause, a_SilenceTruncation, ev_Pause, ev_Record, ev_Resume, p_Append, p_BeepFrequency, p_BeepLength, p_Coder, p_CoderTypes, p_EnabledEvents, p_FileFormat, p_FinalTimeoutBehaviour, p_MaxDuration, p_MinDuration, p_SignalTruncationOn, p_SilenceEnergyThreshold, p_SilenceTerminationOn, p_SilenceTerminationThreshold, p_SilenceTruncationOn, p_SilenceTruncationThreshold, p_SpeechDetectionMode, p_StartBeep, p_StartPaused, q_Silence, rtca_Pause, rtca_Resume, rtca_Stop, rtcc_RecordComplete, v_DetectAllOccurences, v_DetectFirstOccurence, v_GSMFormat, v_Inactive, v_RawFormat, v_WavFormat

Fields inherited from interface hp.telephony.media.CoderConstants

p_AMR_SDPelement, p_channels, p_crc, p_G723_annexa, p_G723_bitrate, p_G729_annexb, p_interleaving, p_maxptime, p_modechangeneighbor, p_modechangeperiod, p_modeset, p_octetalign, p_ptime, p_robustsorting, v_ADPCM_16kG726, v_ADPCM_24k, v_ADPCM_32k, v_ADPCM_32kG726, v_ADPCM_32kOKI, v_ADPCM_44k, v_ALawPCM_48k, v_ALawPCM_64k, v_ALawPCM_88k, v_AMR, v_AMR_WB, v_G723_1b, v_G723_53, v_G723_63, v_G723_no_vad, v_G723_yes, v_G729_no_vad, v_G729_yes, v_G729a, v_GSM, v_Linear16Bit_64k, v_Linear8Bit_48k, v_Linear8Bit_64k, v_Linear8Bit_88k, v_MuLawPCM_48k, v_MuLawPCM_64k, v_MuLawPCM_88k

Fields inherited from interface hp.telephony.media.ASRConstants

a_ASSessionAllocation, a_ASSessionCreation, a_AudioService, e_BadGrammar, e_ResourceUnavailable, e_ServerError, e_ServerFailed, ev_DefineGrammar, ev_DefineGrammer, ev_finalRuleResult, ev_FinalRuleResult, ev_FinalWordResult, ev_NonFinalRuleResult, ev_NonFinalWordResult, p_Grammar, p_GrammarId, p_GrammarType, p_GrammarURI, p_Language, p_LoadGrammar, p_NBestListLength, p_NoInputTimeout, p_Optimize, p_PauseOnIntermediateResult, p_RecogTimeout, p_SaveWaveform, p_SensitivityLevel, p_ServerURL, p_SpeakerName, p_SpeechCompleteTimeout, p_SpeechIncompleteTimeout, p_StubResultIsNoMatch, p_StubResultXML, p_StubResultXMLFile, p_TimersStartImmediately, q_VoiceDetected, rtca_ReleaseCurrentASSession, rtcc_VoiceDetected, v_ASStartTime, v_Call, v_FromFirstOperation, v_OnDemand, v_Operation

Fields inherited from interface hp.telephony.media.SpeechDetectorConstants

p_BargeIn, p_FinalTimeout, p_InitialTimeout, p_InPromptSensitivityPercent, p_Sensitivity, p_Type, q_EndOfSpeechDetected, q_NoSpeechTimeout, q_SpeechDetected, rtca_PromptDone, rtcc_EndOfSpeechDetected, rtcc_NoSpeechTimeout, rtcc_SpeechDetected, v_HP, v_Nvad, v_SwiEp, v_Telisma

Fields inherited from interface hp.telephony.media.FaxConstants

ev_Fax, p_AnswerCED, p_BitRate, p_ByteAlignedEol, p_CapabilityToReceive, p_DataCompressionFormat, p_DeTiffPrefix, p_DeTiffSuffix, p_EnablePolling, p_ErrorCorrection, p_FaxTimeOut, p_FileType, p_InternetRoutingSupport, p_InternetSelectivePollingSupport, p_KeepDataOrder, p_LegalSupport, p_LetterSupport, p_MaxLineToReceive, p_MaxPageToReceive, p_MaxSpeed, p_MinSpeed, p_PageLength, p_PageResolution, p_PagesEncoding, p_PagesPaths, p_PageWidth, p_PasswordSupport, p_PixelArrays, p_Role, p_ScanTimePerLine, p_SelectivePollingSupport, p_SelectivePollingWithSubaddressingSupport, p_StorePath, p_SubaddressingSupport, p_Suffix, p_T37Support, p_T38Support, p_TiffPath, p_VerticalResolution, q_Count, q_Document, q_Page, rtca_AssumeCNG, rtca_Cancel, v_12000bps, v_1216pixelsIn151mm, v_14400bps, v_1728pixelsIn215mm, v_2048pixelsIn255mm, v_2400bps, v_2432pixelsIn303mm, v_33600bps, v_4800bps, v_7200bps, v_864pixelsIn107mm, v_9600bps, v_A4_297mm, v_AfterCNG, v_Answerer, v_B4_364mm, v_BandWarrays, v_BMP, v_Caller, v_DisableECM, v_EnableECM_256bytes, v_EnableECM_64bytes, v_Encoding_MS_BMP, v_Error_Conversion_To_G3, v_Error_Decomp_Init, v_Error_Disconnect, v_Error_File_Open, v_Error_Illegal_Width, v_Error_Page_Format, v_FilesList, v_Fine_196lpi, v_GIF, v_JPEG, v_Normal_98lpi, v_NotSet, v_Page_File_Name_Size, v_PageResolution_0100_0100, v_PageResolution_0200_0100, v_PageResolution_0200_0200, v_PageResolution_0200_0400, v_PageResolution_0300_0300, v_PageResolution_0300_0600, v_PageResolution_0400_0400, v_PageResolution_0400_0800, v_PageResolution_0600_0600, v_PageResolution_0600_1200, v_PageResolution_1200_1200, v_PNG, v_Prefix, v_Rcv_Qual_Bad, v_Rcv_Qual_Medium, v_Rcv_Qual_OK, v_RightNow, v_ST0000, v_ST0505, v_ST1005, v_ST1010, v_ST2010, v_ST2020, v_ST4020, v_ST4040, v_T4_1D_ModifiedHuffman, v_T4_2D_ModifiedRead, v_T4_Buff_Size, v_T6_ModifiedModifiedRead, v_TIFF, v_UnlimitedLength, v_UponRTC

Fields inherited from interface hp.telephony.media.EchoCancellerConstants

p_AcousticEcho, p_AlcInEnable, p_AlcInGain, p_AlcOutEnable, p_AlcOutGain, p_Bypass, p_EchoThreshold, p_MaxDelaySearch, p_Mu, p_NlpControl

Fields inherited from interface hp.telephony.media.RTPRecorderConstants

p_SendSignalsUsingRFC2833

Fields inherited from interface hp.telephony.media.SMSRecorderConstants

e_TL_InternalError, ev_SMS, q_TL_Message, v_TL_DATA_CFM, v_TL_DATA_ERR, v_TL_DATA_IND, v_TL_DATA_REJ, v_TL_EST_CFM, v_TL_EST_REJ, v_TL_INFO_ABRT, v_TL_INFO_CFM, v_TL_INFO_IND, v_TL_INFO_REJ, v_TL_NOT_DLL_EST_IND, v_TL_REL_ABRT, v_TL_REL_CFM, v_TL_REL_IND

Method Summary

void	record(String streamID, RTC[] rtc, Dictionary optargs) Record data from the Terminal into the named Media Stream Container (MSC).

Method Detail

record

public void record(String streamID,
                   RTC[] rtc,
                   Dictionary optargs)
            throws MediaResourceException,
                   AccessControlException

Record data from the Terminal into the named Media Stream Container (MSC). Encode and store data from the telephony network. record() encodes the media stream from the bound Terminal, and stores the result in the Media Stream Container identified by the given streamID.

This method can also be used for sending ASR recognize requests as well as for SMS and, soon, faxes.

If the MSC does not exist, it is created and associated with the coder type specified by parameter p_CoderTypes. (instead of original API using p_Coder ; value is a one element array, the coder type). If the MSC does exist, the recording is made using the coder type associated with that DSD, in case of a WAV file, otherwise, the coder type specified by p_CoderTypes will be used. If the Recorder does not support the indicated Coder, record() throws a MediaResourceException, indicating Error.e_Coder.

This method is non-blocking. The result is passed in a RecorderEvent event through the ResourceEventListener Interface. The condition that caused recording to stop is available from the completion event using getQualifier.

The optargs argument specifies values for Recorder parameters for the duration of this record operation. For example, p_CoderTypes (instead of p_Coder) or p_BeepStart can be overridden for a single method invocation.

Exceptions are thrown if pre- or post- conditions are not satisfied
Pre-conditions:

1. The SDR exists or can be created
2. The SDR is not locked (that is, is not in use)
3. Recorder is Idle
4. Recorder has the required/requested coder

Post-conditions: Record completes normally due to one of:

1. Duration time reached
2. a silence exceeding p_SilenceTerminationThreshold millis detected
3. stop() method invoked
4. RecorderConstants.rtca_Stop triggered

Parameters:

streamID - the String name of the MSC where data is to be stored
or the ASR Audio Service URI in form "rtsp://audioservice"
or the SMS mode in form "sms-tl://"
or the Fax ID prefixed by "fax://".

rtc - an Array of RTC (Run-Time-Control) objects

optargs - a Dictionary of optional arguments among

1. RecorderConstants.p_FileFormat
2. RecorderConstants.p_CoderTypes
3. RecorderConstants.p_Append
4. RecorderConstants.p_EnabledEvents
5. RecorderConstants.p_MaxDuration
6. RecorderConstants.p_MinDuration
7. RecorderConstants.p_SilenceTerminationOn
8. RecorderConstants.p_SilenceTerminationThreshold
9. RecorderConstants.p_SilenceTruncationOn
10. RecorderConstants.p_SilenceTruncationThreshold
11. RecorderConstants.p_SignalTruncationOn
12. RecorderConstants.p_SilenceEnergyThreshold
13. RecorderConstants.p_StartBeep
14. RecorderConstants.p_StartPaused

Throws:

MediaResourceException - if requested operation fails.

AccessControlException

See Also:

ResourceEventListener.onRecorderEvent(hp.telephony.media.RecorderEvent)