📄 mediaoverview.html
字号:
<HTML><HEAD><TITLE>The Java Telephony API Media Package</TITLE></HEAD><BODY BGCOLOR=#ffffff><IMG SRC="images/jtapi-1.1.logo.gif" ALIGN="left"><BR><BR><BR><BR><BR><H1><CENTER>Java Telephony API<BR>Media Extension Package</CENTER></H1><BR><BR><H2><CENTER>January 28, 1997<BR>Version 0.8</CENTER></H2><BR><BR><BR><BR><H2>Introduction<HR></H2><P>This document provides an overview of the Media Extension Package tothe Java Telephony API. This package provides applications access to the mediaon the telephone line. A wide variety of media-centric telephony applicationsexist today, including workstation answering machines, IVR systems,PPP daemons, and fax applications. The Media Package aims to supports virtuallyall media-based telephony applications.</P><P>This overview document is separated into the following sections. A briefdescription of each section follows.</P><OL><A HREF="MediaOverview.html#ARCHITECTURE">Media Package Architecture.</A>This section describes the overall architecture of the Media ExtensionPackage. The Media Package has a base media API which supports all types ofmedia applications. Layered on top of this base layer is a voice-specific API.This high-level voice-specific API supports the most basic and common desktopvoice-telephony applications.</OL><OL><A HREF="MediaOverview.html#VOICE">The Voice API Specification</A>This section describes the voice API part of the Media Extension Package. TheVoice API supports simple voice-based desktop telephony applications. Themethods associated with this part of the package specification are describedhere including a sample application.</OL><BR><BR><H2><A NAME="ARCHITECTURE">Media Package Architecture</A><HR></H2><P>The following diagram shows the bi-level architecture of the Media Package.The lowest or base layer API provides robust support for all types of mediaapplications including desktop voice and answering machines, PPP, IVR, speechsystems, and fax-based applications. The smaller top-layer is a voice-specificAPI, designed to support only the simplest and most common desktop voiceAPI. It is meant as a simple means for application developers to quicklyintegrate media into their desktop voice-telephony applications. Typically,application developers choose only a single layer to use.</P><P><IMG SRC="images/media-arch.gif" ALIGN="middle"></P><H4>Base Media API</H4><P>The base media API supports a wide range of media-based telephonyapplications. This specification does not include details about thisbase-level API yet. This specification will be available in several monthstime. This API supports two other major media-related APIs: the ECTF's S.100API and the Java Media Framework API. The S.100 specification supports buildingadvanced IVR systems, while the Java Media Framework supports advanceddesktop media applications. The Media Package API will support the neccessaryfunctionality from both these media APIs and provide the neccessary hooksto co-exist in their environments.</P><H4>Voice API</H4><P>The Media Package specification available now describes the upper-level voiceAPI. This API supports the most simple voice-based telephony applications. Inthe future, it may be implemented as a high-level wrapper around the robustbase media API.</P><H2><A NAME="VOICE">The Voice API Specification</A><HR></H2><P>The Voice API supports the following functionality: directing voice media fromthe telephone line to a disk file or the workstation's speaker, directingvoice media from a disk file or the workstation's microphone to the telephoneline, and detecting and generating DTMF tones on the telephone line. The VoiceAPI supports the following simple desktop-voice applications: routing thevoice in a telephone call through a workstation's multimedia hardware, simpleworkstation-based voice answering machines, and simple IVR DTMF-basedapplications.</P><H4>The Voice API Terminology</H4><P>The Voice API contains only a half-dozen methods to perform these simpletasks. Many methods are defined in terms of either "playing" or "recording".Depending upon one's perspective, these terms can mean either of two things.For the purpose of this API, "playing" refers to sending (i.e. writing) voicedata to the telephone line. The term "recording" refers to receiving (i.e.reading) voice data from the telephone line.</P><H4>The Voice API Playing Methods</H4><P>The application may route data from the workstation's microphone or from adisk file to the telephone line. Applications use the<EM>useDefaultMicrophone()</EM> to direct the voice data from the defaultworkstation microphone to the telephone line. In the case of several differentmicrophones existing on the workstations at once, the application uses thePhone package to control which microphone is active. The <EM>Phone</EM> packagealso provides the ability to control the gain of the microphone.</P><P>Applicationsuse the <EM>usePlayURL()</EM> to direct the voice data from a URL source to thetelephone line. Voice data can come from either one of these locations at asingle time, but not both at the same time. If an application uses a URL,then the implementation is limited by the availability of that URL and itspermissions to access that URL. Also, the implementation makes no guaranteesabout the real-time behavior if the URL resource is located over the network.The implementation determines which audio file formats it can read. It shouldat the very least read in the same audio file format it writes out. It isthe responsibility of the implementation to determine the audio file formatof the URL provided, and implementation should be able to read the mostcommon format for their particular implementation.</P><P>Applications may begin playing with the <EM>startPlaying()</EM> method andmay stop the playing via the <EM>stopPlaying()</EM> method. Playing may ceasefor other reasons, for example, when the end of the URL-source has beenreached. In either case, events are delivered to the applications to indicatethis state change, i.e. the <EM>MediaTermConnStateEv</EM>. If an applicationcalls <EM>startPlaying()</EM> after it has called <EM>stopPlaying()</EM>,the implementation attempts to read the source media and play it from whereit last left off, if possible. If the application wants to "rewind" themedia, it should re-issue the <EM>usePlayURL()</EM> method.</P><H4>The Voice API Recording Methods</H4><P>The application may route data to the workstation's speaker or to aURL-destination from the telephone line. Applications use the<EM>useDefaultSpeaker()</EM> to direct the voice data to the defaultworkstation speaker from the telephone line. In the case of several differentspeakers existing on the workstations at once, the application uses the<EM>Phone</EM> package to control which speaker is active. The Phone packagealso provides the ability to control the gain of the speaker.</P><P>Application usethe <EM>useRecordURL()</EM> to direct the voice data to a URL-destinationfrom the telephone line. Voice data can go to either one of these locations ata single time, but not both at the same time. If an application uses a URL,then the implementation is limited by the availability of that URL and itspermissions to access that URL. Also, the implementation makes no guaranteesabout the real-time behavior if the URL resource is located over the network.The audio file format is determined by the implementation and should be thea common audio file format for that particular platform. The one constraintimposed on implementation is they must be able to read in the same audio fileformats which they write out.</P><P>Applications may begin recording with the <EM>startRecording()</EM> method andmay stop the recording via the <EM>stopRecording()</EM> method. Recording maycease for other reasons, for example, when the telephone call ends. In eithercase, events are delivered to the applications to indicate this state change,i.e. the <EM>MediaTermConnStateEv</EM>. If an applicationcalls <EM>startRecording()</EM> after it has called <EM>stopRecording()</EM>,the implementation attempts to write to the media from whereit last left off, if possible. If the application wants to "overwrite" themedia, it should re-issue the <EM>useRecordURL()</EM> method.</P> </P><H4>The Voice API DTMF Methods</H4><P>The Voice API provides several methods for applications to detect andgenerate DTMF-tones on the telephone line. Applications use the<EM>setDtmfDetection()</EM> method to turn on and off DTMF-tone detection.Applications receive event notification of all DTMF-tones detected viathe <EM>MediaTermConnDtmfEv</EM> event. Applications use the<EM>generateDtmf()</EM> method to generate a DTMF-tone on the telephone line.It takes a string of characters to generate. These characters may be thedigits zero (0) through nine (9), the letters A through D, the asterisk (*),or the pound(#).</P><H4>The Voice API Events</H4><P>There are several events associated with the voice media package. All ofthese events are reported via the <EM>MediaCallObserver</EM> interface. Thisinterface does not define any new methods, all events are reported via the<EM>callChangedEvent()</EM> method defined in the CallObserver interface. Byimplementing the empty MediaCallObserver interface, the application issignalling to the implementation that it desires media-related call events.</P><P>The media channel associated with the TerminalConnection can either be<EM>available</EM> or <EM>unavailable</EM>. These state changes are reportedvia the <EM>MediaTermConnAvailableEv</EM> and<EM>MediaTermConnUnavailableEv</EM> events. Applications may query for thecurrent channel availability state via the <EM>getMediaAvailability()</EM>method</P><P>There can be either playing, recording, both of these, or no activity onthe media channel. A change in this state is indicated by the<EM>MediaTermConnStateEv</EM> event. The current state is given by a bit-mask.Applications may query for the current playing or recording activity statevia the <EM>getMediaState</EM> method.</P><P>If an application has chosen to detect DTMF-tones on the media channel, itis informed of all DTMF-tones detected via the <EM>MediaTermConnDtmfEv</EM>event. The digit which was detected may be obtained via the<EM>getDtmfDigit()</EM> method on that event.</P><BR><BR><H2>Example Voice API Applications<HR></H2><P>This section presents three application examples which use the voice APIaspect of the Media Extension Package. The first application routes thevoice media from the telephone line to the workstation's default audiohardware, therefore, using the workstation as a telephone. The secondapplication answers incoming telephone calls, plays a store greeting tothe caller, and records a message from the calller, similar to traditionalanswering machines. The third application answers incoming calls andmonitors the telephone line for DTMF-tones (touch-tones). Applications maychoose to perform a certain action based upon this touch-tone input.</P><BR><H4>A Desktop Telephone Application</H4><P>The following code example shows how application route the media on thetelephone line to and from the workstation's default audio hardware. Thisapplication places a telephone call and the user can converse with the otherparty via the workstation.</P><PRE><PRE>import java.telephony.*;import java.telephony.events.*;import java.telephony.media.*;import java.telephony.media.events.*;class DesktopCallObserver implements MediaCallObserver { /* * This CallObserver will be notified of Call events. */ public void callChangedEvent(CallEv evlist[]) { for (int i = 0; i < evlist.length; i++) { CallEv ev = evlist[i]; if (ev instanceof MediaTermConnAvailableEv) {⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -