Microsoft Speech SDK (SAPI 5.0) · SDK 5.1 menu. The binary and source files, projects, are available in the Samples folder of the Microsoft Speech SDK 5.1 folder. A description of

MicrosoftSpeechSDKSAPI5.1

http://go.microsoft.com/fwlink?linkid=288&clcid=0x409

WelcometotheMicrosoftSpeechSDK,version5.1TheMicrosoft®SpeechSDK5.1isthedeveloperkitfortheMicrosoft®Windowsenvironment.Tools,information,andsampleenginesandapplicationsareprovidedtohelpyouintegrateandoptimizeyourspeechrecognitionandspeechsynthesisengineswiththenewMicrosoftSpeechAPI5(SAPI5).TheSpeechSDKalsoincludesupdatedreleasesoftheMicrosoftadvancedspeechrecognitionengineandMicrosoftconcatenatedspeechsynthesisengine.

End-UserLicenseAgreementPleasereadandunderstandtheEnd-UserLicenseAgreementbeforeusingtheMicrosoftSpeechSDK.

RedistributionCodeRightsPleasereadandunderstandtheRedistributableCodeRightsbeforebuildingapplicationsorengines.Thisdocumentoutlineswhichfilesmayberedistributedwithourownproducts.ItalsodescribeslimitationsformodifingtheSpeechSDK5.1filesandsamples.

SystemRequirementsThissectionliststhesoftwarerequiredincludingsupportedoperatingsystemsandthecompilerenvironment.Hardwarerequirementsarealsolistedandincluderecommendedcomputerspeeds,availableRAMandaudioequipment.

DeveloperSupportThissectionprovidesinformationonthedevelopersupportchoicesavailabletoyou.Foradditionalsupportoptions,seesupportphonenumbersandoptions.

GettingStartedforFirst-TimeUsersGettingStartedintroducestheMicrosoft®SpeechSDKtofirst-timeusersandexplainsitscontents,systemrequirements,andfeatures.

ReleaseNotesReleaseNotesdescribesnewinformationatthetimeofrelease,documentsknownissues,andidentifiesanynewredistributionfileupdates.Releasenotesmaybefoundontheinstallationdiskor,ifnotusingadisk,attheinstallationsource.

MicrosoftSpeechTechnologiesWebSiteThissiteprovidesproductnewsupdates,technicalarticles,andlinkstousefulresources.

Isthedocumentationhelpful?We'dliketoknow.Pleasesendanycommentsandsuggestionsyouhaveto:[email protected].

http://go.microsoft.com/fwlink?linkid=288mailto:[email protected]

GettingStartedforFirst-TimeUsersThefollowingtopicsintroducetheMicrosoftSpeechSDK(SDK)tofirst-timeusersandexplainitscontentsandfeatures:

WhatistheSDK?WhatcanIdowiththeSDK?WhatiscoveredintheSDKdocumentation?Programmer'sGuide

WhatisnotcoveredbytheSDK?

HowcanIstartusingtheSDK?

RemovingtheSDKWhatspecialthingsdoIneedtoknow?

WhatistheSDK?MicrosoftSpeechSDKisasoftwaredevelopmentkitforbuildingspeechenginesandapplicationsforMicrosoftWindows.Designedprimarilyforthedesktopspeechdeveloper,theSDKcontainstheMicrosoft®Win32®-compatiblespeechapplicationprogramminginterface(SAPI),theMicrosoftcontinuousspeechrecognitionengineandMicrosoftconcatenatedspeechsynthesis(ortext-to-speech)engine,acollectionofspeech-orienteddevelopmenttoolsforcompilingsourcecodeandexecutingcommands,sampleapplicationandtutorialsthatdemonstratetheuseofSpeechwithotherenginetechnologies,samplespeechrecognitionandspeechsynthesisenginesfortestingwithspeech-enabledapplications,anddocumentationonthemostimportantSDKfeatures.

WhatcanIdowiththeSDK?YoucanusetheSDKcomponentsandredistributable

SAPI/enginerun-timetobuildapplicationsthatincorporatespeechrecognitionandspeechsynthesis.

AutomationSupportSAPI5.1supportsOLEautomation.ThatmeanslanguagesotherthanC/C++maynowuseSAPIforapplicationdevelopment.ThelanguagesthemselvesneedtosupportOLEautomation.CommonlanguageswhichmaybeusedincludesVisualBasic,C#,andJScript.SeeAutomationInterfacesandObjectsforadditionalinformation.OverviewsforautomationandunderstandingtheAPIsuiteforSAPIisfoundatAutomationOverview.ThisisalsoagoodstartingpointforprogrammersnewtoOLEautomationprogramming.

SpeechComponentsandServicesIncludedintheSpeechAPIarchitectureisacollectionofspeechcomponentsfordirectlymanagingtheaudio,trainingwizard,events,grammarcompiler,resources,speechrecognitionmanager,andTTSmanagerforlow-levelcontrolandgreaterflexibility.TheSpeechAPIalsoenablessupportandmanagessharedrecognitioneventsforrunningmultiplespeech-enabledapplications.

SDKToolsThetoolsintheToolsdirectoryassistwiththeverificationandtestingofSAPIdevelopment.Thisdirectorycontainssourcecodeandprojectforcompliancetestingandmaybemodifiedtofityourneeds.

SDKSamplesTheMicrosoftSpeechSDKincludessamplesthatcanbeusedasareferenceforcreatingspeech-enabledapplications.ThecompiledsamplesanddemonstrationapplicationsareavailableontheStart->Programs->MicrosoftSpeech

SDK5.1menu.Thebinaryandsourcefiles,projects,areavailableintheSamplesfolderoftheMicrosoftSpeechSDK5.1folder.Adescriptionofeachsample,installation,andsetofusageinstructionsisprovided.

CoexistenceandThirdPartySupportMicrosoftSpeechAPI5.1hasbeendesignedtocoexistonthesamedevicewithpriorversionsoftheMicrosoftSpeechAPI(versions3.0,4.0,4.0a,and5.0).MicrosoftisalsoworkingwithmanyofthetopspeechrecognitionenginevendorsonprovidingSAPI5support.VisittheThirdPartyProductspageformorethelatestlistonSAPI5-compatibleengines.

Formoreinformationonsetup,seetheMicrosoftSpeechSDKSetup5.1.

WhatiscoveredintheSDKDocumentation?TheMicrosoftSpeechSDKdocumentationprovidesinformationforboththeexperiencedspeechdeveloperandthebeginner.ItislocatedintheStart->Programs->MicrosoftSpeechSDK5.1menu.

Programmer'sGuideTheProgrammer'sGuideprovidesinformationonthefollowingMicrosoftSpeechAPItopics:

C/C++ApplicationlevelinterfacesEnginelevelinterfacesStructures

EnumerationsHelperfunctions


AutomationInterfacesandObjects

Enumerations

SDKSamples,Tools,andTutorialsThissectionincludesdescriptionsandreferencesforthesamples,tools,andtutorialsfortheSAPI5SDK.

EngineComplianceTestingReferenceTheTestingReferencedescribesthecompliancetestingrequirementsforenginevendorsportingtheirspeechenginetoSAPI5.

WhitePapersTheWhitePapersincludetechnicalbackgroundarticlesonthetechnology.Theyalsoincludesamplecodethataddressesmorespecificprogrammingsolutions.

WhatisnotcoveredbytheSpeechSDK?TheMicrosoftSpeechSDKisnotanenduserapplication,GUI,orvoice-userinterface(VUI)developmentenvironmentwithmenus,buttons,toolbars.Itisadevelopmentkitwhichallowsprogrammerstowriteapplicationsincorporatingspeechintothem.ToolsareprovidedintheSDKwhichmayberunfromtheMS-DOS®commandline(e.g.,gc.exe)orwithexecutableapplications.TheMicrosoftSpeechSDKassumesknowledgeofprogrammingforC,C++,oralanguagewhichsupportsOLEautomationsuchasVisualBasic,orC#.SAPIhasastrongrelianceonCOM.AlthoughdirectexperiencewithCOMorCOMprogrammingisnotrequired,understandingCOMprincipleswillmakeprogrammingandapplicationdesigneasier.

HowcanIstartusingtheSDK?TheorganizationoftheSpeechSDKdocumentationissimilartoothertraditionalMicrosoftSDKs.TheFindingInformationsectionoftheMicrosoftSpeechSDKdocumentationcontainsimportantinformationonhowtousethedocumentation'sHelpViewer,includinguseofthetoolbarbuttonsandfulltextsearch,andfindingaHelptopic,andmuchmore.VisittheMicrosoft®Speech.NETTechnologieshomepagefrequently.HereyoucanfindthelatestnewsandupdatestotheSDKandtheMicrosoftspeechengines.Ifforsomereasonyoucannotlocateaparticulartypeofdocumentationinthehelpsystem,[email protected].

RemovingtheSDKIfyouwanttoremovetheSAPISDKfromthecomputer,useAdd/RemoveProgramspropertiesfromControlPanel(Start->Settings->ControlPanel).Itisnotadvisedtodeleteindividualfiles.However,onlyoneversionoftheSDKmaybeinstalledatatime.AttemptstoinstallanewerversionofSAPIwithapreviouseditionalreadyloadedwillprompttheinstallationpackagetoremoveSAPIfirst.AfterremovingSAPIinthismanner,theinstallermayberunagainandthenewversionwillbeloaded.

WhatspecialthingsdoIneedtoknow?IfyouaredevelopinganapplicationthatintendstousetheMicrosoftspeechsetupfiles,yourSetup.exeneedstoinstalltheMicrosoftWindowsInstallerifitisnotalreadypresent.PleasegotoWindowsInstaller1.5downloadpage,orPlatformSDKStartPagetodownloadtheWindowsInstallerSDKandsearchfor"WindowsInstaller".

http://go.microsoft.com/fwlink?linkid=288&clcid=0x409mailto:[email protected]://go.microsoft.com/fwlink/?linkid=735&clcid=0x409http://go.microsoft.com/fwlink/?LinkId=3199&clcid=0x409

SystemRequirementsOperatingSystemsSupportedoperatingsystemsare:

WindowsXPProfessionalorHomeeditions;alllanguageversions.Windows.NETServereditions;alllanguageversions.MicrosoftWindows2000ProfessionalWorkstationorServer;alllanguageversions.MicrosoftWindowsMillenniumedition.

MicrosoftWindows98alleditions.MicrosoftWindows®NTWorkstationorServer4.0,servicepack6a,English,Japanese,orSimplifiedChineseedition.

Windows95orearlierisnotsupported.

SoftwareRequirementsMicrosoftInternetExplorer5.0orlaterversion.UsersofWindowsNT4withanyversionoftheservicepacksrequireMicrosoftInternetExplorer5.5orlater.DownloadthelatestversionofMicrosoftInternetExplorer.MicrosoftVisualC++6.0,servicepack3orlaterversionisneededtoruntheSAPI5SDKsamples.Ingeneral,any32-bitCcompilerwillworkforwritingSAPIapplications.MicrosoftVisualBasicisneededtowriteapplicationsincorporatingSAPIautomation,orforcompilingtheVisualBasicsamplecode.SinceSAPIsupportsCOMautomation,otherlanguagesandcompilersmaybeusedwithSAPIautomationprovideditsupportsOLEautomation.MicrosoftVisualStudio7,alsocalledVisual

http://go.microsoft.com/fwlink/?LinkId=361&clcid=0x409

Studio.NET,isneededtocompiletheC#examples.PlatformSDKisgenerallynotneededalthoughsomesamplesandfunctionalitymayrequireit.Seethespecificsamplesforconfirmation.Ifrequired,seeMicrosoftPlatformSDKforloadinginformation.

HardwareRequirementsAPentiumII\PentiumII-equivalentorlaterprocessorat233MHzwith128megabytes(MB)ofRAMisrecommended.SAPI5cannowtakeadvantageofacomputerandoperatingsystemthatsupportsmultipleprocessors,includingallthosementionedabove.Additionally,youcanuseSAPI5inadistributedapplicationenvironment.Amicrophoneorsomeothersoundinputdevicetoreceivethesoundisrequiredforspeechrecognition.Ingeneral,themicrophoneshouldbeahighqualitydevicewithnoisefiltersbuiltin.Thespeechrecognitionrateisdirectlyrelatedtothequalityoftheinput.Therecognitionratewillbesignificantlylowerorperhapsevenunacceptablewithapoormicrophone.

NotallsoundcardsorsounddevicesaresupportedbySAPI5,eveniftheoperatingsystemsupportsthemotherwise.ThefollowingtableoutlinestheRAMusage:

ComponentMinimumRAMRecommendedRAM

TTSEngine 14.5MB 32MBSRCommandandControl

16MB 32MB

SRDictation 25.5MB 128MB

SRBoth 26.5MB 128MB

Thefollowingtableoutlinesthediskusage:

FileNameApproximateFileSize

SetupMergeNames

Sapi.dllandSapisvr.exe

0.5MB Sp5.msm

Sapi.cpl 36KB Sp5Intl.msmSREngine 1.7MB Sp5Sr.msmCommandandControlDatafiles

13.4MB Sp5CCInt.msm

TTSEngineandvoices

7.8MB Sp5TTInt.msm

FilescommontobothMicrosoftSAPI5.1TTSandSR.

92KB SpCommon.Msm

Language-specificSAPI5.1inversetextnormalization(ITN)components.

108KB Sp5itn.Msm

Formoreinformationonsetup,seetheMicrosoftSpeechSDKSetup5.1.

MicrosoftSpeechSoftwareDevelopmentKit,Version5.1

MicrosoftSpeechSoftwareDevelopmentKit,Version5.1END-USERLICENSEAGREEMENTFORMICROSOFTSOFTWAREIMPORTANT-READCAREFULLY:ThisMicrosoftEnd-UserLicenseAgreement("EULA")isalegalagreementbetweenyou(eitheranindividualorasingleentity)andMicrosoftCorporationfortheMicrosoftsoftwareproductidentifiedabove,whichincludesDEVICEsoftware(includingSAPI5.1,MicrosoftcontinuousspeechrecognitionengineandMicrosoftconcatenativespeechsynthesisengine),andmayincludeassociatedmedia,printedmaterials,and"online"orelectronicdocumentation("SOFTWAREPRODUCT").TheSOFTWAREPRODUCTalsoincludesanyupdatesandsupplementstotheoriginalSOFTWAREPRODUCTprovidedtoyoubyMicrosoft.AnysoftwarethatmaybeprovidedalongwiththeSOFTWAREPRODUCTthatisassociatedwithaseparateend-userlicenseagreementislicensedtoyouunderthetermsofthatlicenseagreement.Byinstalling,copying,downloading,accessingorotherwiseusingtheSOFTWAREPRODUCT,youagreetobeboundbythetermsofthisEULA.IfyoudonotagreetothetermsofthisEULA,donotinstallorusetheSOFTWAREPRODUCT.

SOFTWAREPRODUCTLICENSETheSOFTWAREPRODUCTisprotectedbycopyrightlawsandinternationalcopyrighttreaties,aswellasotherintellectualpropertylawsandtreaties.TheSOFTWAREPRODUCTislicensed,notsold.

1.GRANTOFLICENSE.ThisEULAgrantsyouthefollowingrights:-SOFTWAREPRODUCT.YoumayinstallcopiesoftheSOFTWAREPRODUCTonuptoten(10)digitalelectronicdevices,includingcomputers,workstations,terminals,handheldPCs,pagers,"smartphones,"orotherdigitalelectronicdevices(eacha"DEVICE")todesign,develop,andtestsoftwareprogramsthatusetheMicrosoftSpeechApplicationProgrammingInterface("SAPI5.1")andrunononeormoreMicrosoftWindowsoperatingsystemproductsthatsupportSAPI5.1("WindowsPlatforms"),providedthatyouaretheonlyindividualusingtheSOFTWAREPRODUCToneachsuchDEVICE.Ifyouareasingleentity,youmaydesignateoneindividualwithinyourorganizationtohavetherighttousetheSOFTWAREPRODUCTinthemannerdescribedherein.-SampleCode.SolelywithrespecttothoseportionsoftheSOFTWAREPRODUCTidentifiedassamplecode("SampleCode"),MicrosoftalsograntsyoutherighttomodifythesourcecodeversionoftheSampleCodeforthesolepurposesofdesigning,developing,andtestingsoftwareprogramsthatuseSAPI5.1(each,"aSAPIApplication")andtoreproduceanddistributetheSampleCodealongwithanymodificationsthereof,inobjectcodeformonly,providedthatyoucomplywiththeDistributionRequirementsdescribedbelow.Forpurposesofthissection,"modifications"shallmeanenhancementstothefunctionalityoftheSampleCode.

-RedistributableCode.PortionsoftheSOFTWAREPRODUCTaredesignatedas"RedistributableCode"filelocatedinREDISTRIB.CHM.YourdistributionrightsassociatedwitheachfileoftheRedistributableCodearesubjecttothedistributionrequirementsdescribedbelow.-DistributionRequirements.YoumaycopyandredistributetheSampleCodeand/orRedistributableCode(collectively"REDISTRIBUTABLECOMPONENTS")asdescribedabove,providedthat(a)youdistributetheREDISTRIBUTABLECOMPONENTSonlyinconjunctionwith,andasapartof,yourSAPIApplication;(b)yourSAPIApplicationaddssignificantandprimaryfunctionalitytotheREDISTRIBUTABLECOMPONENTS;(c)theREDISTRIBUTABLECOMPONENTSonlyoperateinconjunctionwiththeWindowsPlatforms;(d)youdonotpermitfurtherredistributionoftheREDISTRIBUTABLECOMPONENTSbyyourend-usercustomers;(e)youdonotuseMicrosoft'sname,logo,ortrademarkstomarketyourSAPIApplication;(f)youincludeavalidcopyrightnoticeonyourSAPIApplication;(g)youincludetheentiretextlocatedinREDISTRIB.CHMinyourSAPIApplicationEndUserLicenseAgreement;and(h)youagreetoindemnify,holdharmless,anddefendMicrosoftfromandagainstanyclaimsorlawsuits,includingattorneys'fees,thatariseorresultfromtheuseordistributionofyourSAPIApplication.ContactMicrosoftfortheapplicableroyaltiesdueandotherlicensingtermsforallotherusesand/ordistributionoftheREDISTRIBUTABLECOMPONENTS.-ReservationofRights.AllrightsnotexpresslygrantedarereservedbyMicrosoft.

2.DESCRIPTIONOFOTHERRIGHTSANDLIMITATIONS.-LimitationsonReverseEngineering,Decompilation,andDisassembly.Youmaynotreverseengineer,decompile,ordisassembletheSOFTWAREPRODUCT,exceptandonlytotheextentthatsuchactivityisexpresslypermittedbyapplicablelawnotwithstandingthislimitation.

-SeparationofComponents.TheSOFTWAREPRODUCTislicensedasasingleproduct.ItscomponentpartsmaynotbeseparatedforuseonmorethanoneDEVICE.-Trademarks.ThisEULAdoesnotgrantyouanyrightsinconnectionwithanytrademarksorservicemarksofMicrosoft.-Rental.Youmaynotrent,lease,orlendtheSOFTWAREPRODUCT.-SupportServices.NotechnicalsupportwillbeprovidedfortheSOFTWAREPRODUCT.-Termination.Withoutprejudicetoanyotherrights,MicrosoftmayterminatethisEULAifyoufailtocomplywiththetermsandconditionsofthisEULA.Insuchevent,youmustdestroyallcopiesoftheSOFTWAREPRODUCTandallofitscomponentparts.

3.COPYRIGHT.AlltitleandcopyrightsinandtotheSOFTWAREPRODUCT(includingbutnotlimitedtoanyimages,photographs,animations,video,audio,music,text,and"applets"incorporatedintotheSOFTWAREPRODUCT),theaccompanyingprintedmaterials,andanycopiesoftheSOFTWAREPRODUCTareownedbyMicrosoftoritssuppliers.AlltitleandintellectualpropertyrightsinandtothecontentthatmaybeaccessedthroughuseoftheSOFTWAREPRODUCTisthepropertyoftherespectivecontentownerandmaybeprotectedbyapplicablecopyrightorotherintellectualpropertylawsandtreaties.ThisEULAgrantsyounorightstousesuchcontent.IfthisSOFTWAREPRODUCTcontainsdocumentationthatisprovidedonlyinelectronicform,youmayprintonecopyofsuchelectronicdocumentation.YoumaynotcopytheprintedmaterialsaccompanyingtheSOFTWAREPRODUCT.

4.DUAL-MEDIASOFTWARE.YoumayreceivetheSOFTWAREPRODUCTinmorethanonemedium.Regardlessofthetypeorsizeofmediumyoureceive,youmayuseonlyonemediumthatisappropriateforyoursingleDEVICE.Youmaynotinstall,copyorusetheothermediumonanotherDEVICE.Youmaynotloan,rent,lease,orotherwisetransfertheothermediumtoanotheruser,exceptaspartofthepermanenttransfer(asprovidedabove)oftheSOFTWAREPRODUCT.

5.U.S.GOVERNMENTRESTRICTEDRIGHTS.AllSOFTWAREPRODUCTSprovidedtotheU.S.GovernmentpursuanttosolicitationsissuedonorafterDecember1,1995isprovidedwiththecommerciallicenserightsandrestrictionsdescribedelsewhereherein.AllSOFTWAREPRODUCTSprovidedtotheU.S.GovernmentpursuanttosolicitationsissuedpriortoDecember1,1995isprovidedwith"RestrictedRights"asprovidedforinFAR,48CFR52.227-14(JUNE1987)orDFAR,48CFR252.227-7013(OCT1988),asapplicable.TheresellerisresponsibleforensuringthattheSOFTWAREPRODUCTismarkedwiththe"RestrictedRightsNotice"or"RestrictedRightsLegend,"asrequired.Allrightsnotexpresslygrantedarereserved.

6.EXPORTRESTRICTIONS.YouacknowledgethattheSOFTWAREPRODUCTisofU.S.origin.YouagreetocomplywithallapplicableinternationalandnationallawsthatapplytotheSOFTWAREPRODUCT,includingtheU.S.ExportAdministrationRegulations,aswellasend-user,end-useandcountry/regiondestinationrestrictionsissuedbyU.S.andothergovernments.ForadditionalinformationonexportingMicrosoftproducts,seehttp://www.microsoft.com/exporting/.

MISCELLANEOUS.IfyouacquiredthisSOFTWAREPRODUCTintheUnitedStates,thisEULAisgovernedbythelawsoftheStateofWashington.IfyouacquiredthisSOFTWAREPRODUCTinCanada,unlessexpresslyprohibitedbylocallaw,thisEULAisgovernedbythelawsinforceintheProvinceofOntario,Canada;and,inrespectofanydisputewhichmayarisehereunder,youconsenttothejurisdictionofthefederalandprovincialcourtssittinginToronto,Ontario.IfthisSOFTWAREPRODUCTwasacquiredoutsidetheUnitedStates,thenlocallawmayapply.ShouldyouhaveanyquestionsconcerningthisEULA,orifyoudesiretocontactMicrosoftforanyreason,pleasecontacttheMicrosoftsubsidiaryservingyourcountry/region,ore-mail:[email protected]

NOWARRANTIES.MICROSOFTEXPRESSLYDISCLAIMSANYWARRANTYFORTHESOFTWAREPRODUCT.THESOFTWAREPRODUCTANDANYRELATEDDOCUMENTATIONISPROVIDED"ASIS"WITHOUTWARRANTYOFANYKIND,EITHEREXPRESSORIMPLIED,INCLUDING,WITHOUTLIMITATION,THEIMPLIEDWARRANTIESORMERCHANTABILITY,FITNESSFORAPARTICULARPURPOSE,ORNONINFRINGEMENT.THEENTIRERISKARISINGOUTOFUSEORPERFORMANCEOFTHESOFTWAREPRODUCTREMAINSWITHYOU.LIMITATIONOFLIABILITY.TOTHEMAXIMUMEXTENTPERMITTEDBYAPPLICABLELAW,INNOEVENTSHALLMICROSOFTORITSSUPPLIERSBELIABLEFORANYSPECIAL,INCIDENTAL,INDIRECT,ORCONSEQUENTIALDAMAGESWHATSOEVER(INCLUDING,WITHOUTLIMITATION,DAMAGESFORLOSSOFBUSINESSPROFITS,BUSINESSINTERRUPTION,LOSSOFBUSINESSINFORMATION,ORANYOTHERPECUNIARYLOSS)ARISINGOUTOFTHEUSEOFORINABILITYTOUSETHESOFTWAREPRODUCTORTHEPROVISIONOFORFAILURETOPROVIDESUPPORT

SERVICES,EVENIFMICROSOFTHASBEENADVISEDOFTHEPOSSIBILITYOFSUCHDAMAGES.BECAUSESOMESTATESANDJURISDICTIONSDONOTALLOWTHEEXCLUSIONORLIMITATIONOFLIABILITY,THEABOVELIMITATIONMAYNOTAPPLYTOYOU.

EXCLUSIONDEGARANTIE.MICROSOFTEXCLUTEXPRESSÉMENTTOUTEGARANTIERELATIVEAUPRODUITLOGICIEL.LEPRODUITLOGICIELETLADOCUMENTATIONYAFFÉRENTESONTFOURNIS"ENL'ÉTAT",SANSGARANTIED'AUCUNESORTE,EXPRESSEOUIMPLICITE,NOTAMMENTSANSAUCUNEGARANTIEIMPLICITEDEQUALITÉ,D'ADÉQUATIONÀUNUSAGEPARTICULIEROUD'ABSENCEDECONTREFAÇON.VOUSASSUMEZL'ENSEMBLEDESRISQUESDÉCOULANTDEL'UTILISATIONOUDESPERFORMANCESDUPRODUITLOGICIEL.LEPRÉSENTARTICLEESTSANSPRÉJUDICEDELAGARANTIELÉGALECONTRELESVICESCACHÉSDONTVOUSPOURRIEZBÉNÉFICIER,LECASÉCHÉANT.LIMITATIONDERESPONSABILITÉ.DANSTOUTELAMESUREPERMISEPARLARÉGLEMENTATIONENVIGUEUR,MICROSOFTOUSESFOURNISSEURSNEPOURRONTENAUCUNCASÊTRETENUSPOURRESPONSABLESDETOUTDOMMAGE,DEQUELQUENATUREQUECESOIT,(NOTAMMENTETDEMANIÈRENONLIMITATIVE,TOUTEPERTEDEBÉNÉFICES,INTERRUPTIOND'ACTIVITÉ,PERTED'INFORMATIONSCOMMERCIALESOUTOUTEAUTREPERTEPÉCUNIAIRE)RÉSULTANTDEL'UTILISATIONOUDEL'IMPOSSIBILITÉD'UTILISERLEPRODUITLOGICIELOUDELAFOURNITUREOUDUDÉFAUTDEFOURNITUREDESSERVICESD'ASSISTANCE,MÊMESIMICROSOFTAÉTÉPRÉVENUDEL'ÉVENTUALITÉDETELSDOMMAGES.CERTAINSPAYSETCERTAINESJURIDICTIONSN'AUTORISENTPASLESEXCLUSIONSOULIMITATIONSDERESPONSABILITÉ,DESORTEQUELALIMITATIONCI-DESSUSPEUTNEPASVOUSÊTREAPPLICABLE.

AbouttheSDKTheMicrosoftSpeechSDKisdesignedtoworkwiththeindustry-leadingSpeechApplicationProgrammingInterface(SAPI)andMicrosoftcontinuousspeechrecognitionengineandMicrosoftconcatenatedspeechsynthesisengine(ortext-to-speech).MicrosoftSDKincludestools,samples,anddocumentationforbuildingspeechapplications.

MicrosoftVisualBasicSupportAsetofCOM-supportedspeechAutomationinterfacesisincludedinthisreleaseofMicrosoftSpeechSDK.ThatmeanslanguagesotherthanC/C++maynowuseSAPIforapplicationdevelopment.ThelanguagesthemselvesneedtosupportOLEautomation.CommonlanguageswhichmaybeusedincludesVisualBasic,C#,andJScript.SeeAutomationInterfacesandObjectsforadditionalinformation.

Thissectionincludesthefollowingtopics:LegalInformationRedistributableCodeRights

WhoShouldUseThisSDKHowtoReadNewsgroups

DeveloperSupportPlatformSDKRequirements

LegalInformationforMicrosoftSpeechSDKInformationinthisdocumentissubjecttochangewithoutnoticeanddoesnotrepresentacommitmentonthepartofMicrosoftCorporation.Companies,names,anddatausedinexampleshereinarefictitiousunlessotherwisenoted.Nopartofthisdocumentmaybereproducedortransmittedinanyformorbyanymeans,electronicormechanical,foranypurpose,unlessexpresslypermittedbyMicrosoftCorporation.Microsoftmayhavepatentsorpendingpatentapplications,trademarks,copyrights,orotherintellectualpropertyrightscoveringsubjectmatterinthisdocument.Thefurnishingofthisdocumentdoesnotgiveyouanylicensetothesepatents,trademarks,copyrights,orotherintellectualpropertyrights.

©1995-2000MicrosoftCorporation.Allrightsreserved.

MicrosoftSpeechSoftwareDevelopmentKit,Version5.1

RedistributableCodeTheRedistributableCodeisthepropertyofMicrosoftCorporationanditssuppliersandisprotectedbycopyrightlawandinternationaltreatyprovisions.YouareauthorizedtomakeandusecopiesoftheRedistributableCodeeitheraspartoftheapplicationinwhichyoureceivedtheRedistributableCode,orinconjunctionwiththeapplicationforwhichitsuseisintended.Exceptasexpresslyprovidedintheforegoingsentence,youarenotauthorizedtoreproduceanddistributetheRedistributableCode.Microsoftreservesallrightsnotexpresslygranted.Youmaynotreverseengineer,decompile,ordisassembletheRedistributableCode,exceptandonlytotheextentthatsuchactivityisexpresslypermittedbyapplicablelawnotwithstandingthislimitation.THEREDISTRIBUTABLECODEISPROVIDEDTOYOU"ASIS"WITHOUTWARRANTYOFANYKIND,EITHEREXPRESSORIMPLIED,INCLUDINGBUTNOTLIMITEDTOTHEIMPLIEDWARRANTIESOFMERCHANTABILITYAND/ORFITNESSFORAPARTICULARPURPOSE.YOUASSUMETHEENTIRERISKASTOTHEACCURACYANDTHEUSEOFTHEREDISTRIBUTABLECODE.MICROSOFTSHALLNOTBELIABLEFORANYDAMAGESWHATSOEVERARISINGOUTOFTHEUSEOFORINABILITYTOUSETHEREDISTRIBUTABLECODE,EVENIFMICROSOFTHASBEENADVISEDOFTHEPOSSIBILITYOFSUCHDAMAGE.

RedistributableCodeRedistributableCodeisidentifiedasthefollowingfilesandallofthefilescanbefoundatthefollowinglocation:

LicensingMicrosoftSpeechTechnology


WhoShouldUseThisSDKTogetthemostoutofthisSDK,youshouldbefamiliarwiththefollowing:

C/C++programmingconcepts.VisualBasicprogrammingconcepts.SAPI5.1supportsOLEautomationsothatanylanguagecapableofaccessingautomationobjectsmaybeused.VisualBasicisawidespreadandpopularapplicationthatsupportsOLEautomation.AsaresultmanyofSAPISDK'ssamplesandAPIreferencesfollowVisualBasicsyntax.Thereis,however,norequirementtouseVisualBasicforOLEautomation.

ComponentObjectModel(COM).DevelopersshouldunderstandCOMprogrammingconcepts,obtainingpointerstointerfaces,andcallingmethods.

AlldevelopersshouldunderstandtheWin32applicationprogramminginterface(API).

FormoreinformationaboutWindowsprogramming,seethedocumentationincludedintheMicrosoftWin32SoftwareDevelopmentKit.FormoreinformationaboutC/C++programming,seethedocumentationfortheMicrosoft®VisualC++™developmentsystemforWindows.

MicrosoftSpeechRecognitionNewsgroups

HowtoReadNewsgroupsYoucanuseanynewsreadersoftwaretoaccesstheMicrosoftnewsgroups.MicrosoftOutlookExpressisinstalledaspartofMicrosoftInternetExplorerforyourconvenience.VisittheMicrosoftInternetExplorerHomepageforinformationonhowtodownloadandinstallthisproduct.WithOutlookExpressinstalled,afteryouclickanewsgrouplink,youwillbepromptedforconfigurationinformation.WhenpromptedforNewsServer,specifynewsvr.Youdonotneedtoenteranaccountnameorpassword;makesurethattheoptionThisServerRequiresMeToLogOnisnotcheckedontheServertaboftheNewsReaderpropertieswindow.IfyouareusinganNNTPnewsreader(sometimescalledanewsclient)otherthanOutlookExpress,besuretoconfigureittoreadtheMicrosoftnewsgroups.YoucanaccesstheMicrosoftnewsserveratthesameaddressabovewithnewsvr.Beforepostingtothenewsgroups,pleasereviewtheMicrosoftNewsgroupRulesofConduct.

http://go.microsoft.com/fwlink/?linkid=361&clcid=0x409http://go.microsoft.com/fwlink/?LinkId=2889

AvailableNewsgroupsMicrosoftNewsgroupslistsavailablenewsgroupsfromMicrosoft.

http://go.microsoft.com/fwlink/?LinkId=2890

DeveloperSupportMicrosoftSupportCenterTheMicrosoftSupportCentersitemaintainsawealthofresourcestohelpyougetthemostfromyourproduct.HereyoucansearchtheentireKnowledgeBase,viewallthetroubleshootingwizards,andaccessallthedownloadablefiles.Youcanalsoviewtheextensiveonlineglossaryofcomputerterms,andfindphonenumbersandsupportoptionsforallMicrosoftproducts.

SpeechnewsgroupsForassistancewithspecificproblems,checkfirstwiththefollowingnewsgroup.Foradviceonconfiguringanewsreader,seeHowtoReadNewsgroups.

microsoft.public.speech_tech.sdk

MicrosoftSpeech.NETTechnologiesFeedbackIfyouhavefeedbackontheMicrosoftSpeechAPI(SAPI)orotherMicrosoftSpeech-relatedquestions,pleasesendane-mailmessagetothefollowingaddress.Thise-mailaddressismonitoredregularly,butquestionswillreceiveonlylimitedresponse.Pleaseusethenewsgroupforumaboveformostquestionsandinquiries.

[email protected]

KnownIssuesInformationonknownissuesinSAPI5canbefoundintheKnowledgeBasearticlesintheMicrosoftSpeech.NETTechnologiessupporthomepage.

http://go.microsoft.com/fwlink/?LinkId=2891mailto:[email protected]://go.microsoft.com/fwlink?linkid=288&clcid=0x409

MicrosoftPlatformSDKTheMicrosoftPlatformSDK(PSDK)isnotarequirementingeneralforusingSAPI.However,atleastoneSDKsampledoesrequireit.Othermanufacturesproductsmayalsorequireitfortheirproducts.CheckwiththespecificSDKsampleormanufacturer'sproductforcompletedetails.SAPI5.1SDKSamplesRequiringPSDK

SimpleTelephonySampleSpeechRecognitionEngine

DownloadPSDKIfthePSDKisneeded,itmaydownloadedfromtheMicrosoftPlatformSDKsite.

http://go.microsoft.com/fwlink/?LinkId=633

RequirementsPlatformSDK(PSDK)April2000orlateredition.CompilingSDKprojectsrequirescomponentsofthePSDK.WithinMicrosoftVisualC++6.0,thePSDKincludedirectoriesmustbelistedbeforetheVisualC++.UsetheDirectoriestabtochangetheorderintheTools->Optionsmenu.MovePSDKdirectoriesaboveallVisualC++directories,ifneeded.

Tosavediskspace,youcanloadaminimalconfiguration.Thisincludesenablingonlythefollowingtwooptions:

1. ConfigurationOptions

2. BuildEnvironment

Theseoptionsmayrequire13MBonthesystemdriveandanother80MBonanyotherdrive.Nootheroptionsareneeded.

SAPI5IntroductionThissectionprovidesaSAPI5introduction.Thefollowingtopicisavailable:

SAPI5Overview

SAPI5OverviewTheSAPIapplicationprogramminginterface(API)dramaticallyreducesthecodeoverheadrequiredforanapplicationtousespeechrecognitionandtext-to-speech,makingspeechtechnologymoreaccessibleandrobustforawiderangeofapplications.Thissectioncoversthefollowingtopics:APIOverviewAPIforText-to-SpeechAPIforSpeechRecognition

APIOverviewTheSAPIAPIprovidesahigh-levelinterfacebetweenanapplicationandspeechengines.SAPIimplementsallthelow-leveldetailsneededtocontrolandmanagethereal-timeoperationsofvariousspeechengines.ThetwobasictypesofSAPIenginesaretext-to-speech(TTS)systemsandspeechrecognizers.TTSsystemssynthesizetextstringsandfilesintospokenaudiousingsyntheticvoices.Speechrecognizersconverthumanspokenaudiointoreadabletextstringsandfiles.

APIforText-to-SpeechApplicationscancontroltext-to-speech(TTS)usingtheISpVoiceComponentObjectModel(COM)interface.OnceanapplicationhascreatedanISpVoiceobject(seeText-to-SpeechTutorial),theapplicationonlyneedstocallISpVoice::Speaktogeneratespeechoutputfromsometextdata.Inaddition,theIspVoiceinterfacealsoprovidesseveralmethodsforchangingvoiceandsynthesispropertiessuchasspeakingrateISpVoice::SetRate,outputvolumeISpVoice::SetVolumeandchangingthecurrentspeakingvoiceISpVoice::SetVoiceSpecialSAPIcontrolscanalsobeinsertedalongwiththeinputtexttochangereal-timesynthesispropertieslikevoice,pitch,wordemphasis,speakingrateandvolume.Thissynthesismarkupsapi.xsd,usingstandardXMLformat,isasimplebutpowerfulwaytocustomizetheTTSspeech,independentofthespecificengineorvoicecurrentlyinuse.TheIspVoice::Speakmethodcanoperateeithersynchronously(returnonlywhencompletelyfinishedspeaking)orasynchronously(returnimmediatelyandspeakasabackgroundprocess).Whenspeakingasynchronously(SPF_ASYNC),real-timestatusinformationsuchasspeakingstateandcurrenttextlocationcanpolledusingISpVoice::GetStatus.Alsowhilespeakingasynchronously,newtextcanbespokenbyeitherimmediatelyinterruptingthecurrentoutput(SPF_PURGEBEFORESPEAK),orbyautomaticallyappendingthenewtexttotheendofthecurrentoutput.InadditiontotheISpVoiceinterface,SAPIalsoprovidesmanyutilityCOMinterfacesforthemoreadvancedTTSapplications.

EventsSAPIcommunicateswithapplicationsbysendingeventsusingstandardcallbackmechanisms(WindowMessage,callbackprocorWin32Event).ForTTS,eventsaremostlyusedfor

synchronizingtotheoutputspeech.Applicationscansynctoreal-timeactionsastheyoccursuchaswordboundaries,phonemeorviseme(mouthanimation)boundariesorapplicationcustombookmarks.Applicationscaninitializeandhandlethesereal-timeeventsusingISpNotifySource,ISpNotifySink,ISpNotifyTranslator,ISpEventSink,ISpEventSource,andISpNotifyCallback.

LexiconsApplicationscanprovidecustomwordpronunciationsforspeechsynthesisenginesusingmethodsprovidedbyISpContainerLexicon,ISpLexiconandISpPhoneConverter.

ResourcesFindingandselectingSAPIspeechdatasuchasvoicefilesandpronunciationlexiconscanbehandledbythefollowingCOMinterfaces:ISpDataKey,ISpRegDataKey,ISpObjectTokenInit,ISpObjectTokenCategory,ISpObjectToken,IEnumSpObjectTokens,ISpObjectWithToken,ISpResourceManagerandISpTask.

AudioFinally,there’saninterfaceforcustomizingtheaudiooutputtosomespecialdestinationsuchastelephonyandcustomhardware(ISpAudio,ISpMMSysAudio,ISpStream,ISpStreamFormat,ISpStreamFormatConverter).Backtotop

APIforSpeechRecognitionJustasISpVoiceisthemaininterfaceforspeechsynthesis,ISpRecoContextisthemaininterfaceforspeechrecognition.LiketheISpVoice,itisanISpEventSource,whichmeansthatitisthespeechapplication'svehicleforreceivingnotificationsfortherequestedspeechrecognitionevents.Anapplicationhasthechoiceoftwodifferenttypesofspeechrecognitionengines(ISpRecognizer).Asharedrecognizerthatcouldpossiblybesharedwithotherspeechrecognitionapplicationsisrecommendedformostspeechapplications.TocreateanISpRecoContextforasharedISpRecognizer,anapplicationneedonlycallCOM'sCoCreateInstanceonthecomponentCLSID_SpSharedRecoContext.Inthiscase,SAPIwillsetuptheaudioinputstream,settingittoSAPI'sdefaultaudioinputstream.Forlargeserverapplicationsthatwouldrunaloneonasystem,andforwhichperformanceiskey,anInProcspeechrecognitionengineismoreappropriate.InordertocreateanISpRecoContextforanInProcISpRecognizer,theapplicationmustfirstcallCoCreateInstanceonthecomponentCLSID_SpInprocRecoInstancetocreateitsownInProcISpRecognizer.ThentheapplicationmustmakeacalltoISpRecognizer::SetInput(seealsoISpObjectToken)inordertosetuptheaudioinput.Finally,theapplicationcancallISpRecognizer::CreateRecoContexttoobtainanISpRecoContext.Thenextstepistosetupnotificationsforeventstheapplicationisinterestedin.AstheISpRecognizerisalsoanISpEventSource,whichinturnisanISpNotifySource,theapplicationcancalloneoftheISpNotifySourcemethodsfromitsISpRecoContexttoindicatewheretheeventsforthatISpRecoContextshouldbereported.ThenitshouldcallISpEventSource::SetInteresttoindicatewhicheventsitneedstobenotifiedof.ThemostimportanteventistheSPEI_RECOGNITION,whichindicatesthattheISpRecognizerhasrecognizedsomespeechforthisISpRecoContext.SeeSPEVENTENUMfordetailsontheother

availablespeechrecognitionevents.Finally,aspeechapplicationmustcreate,load,andactivateanISpRecoGrammar,whichessentiallyindicateswhattypeofutterancestorecognize,i.e.,dictationoracommandandcontrolgrammar.First,theapplicationcreatesanISpRecoGrammarusingISpRecoContext::CreateGrammar.Then,theapplicationloadstheappropriategrammar,eitherbycallingISpRecoGrammar::LoadDictationfordictationoroneoftheISpRecoGrammar::LoadCmdxxxmethodsforcommandandcontrol.Finally,inordertoactivatethesegrammarssothatrecognitioncanstart,theapplicationcallsISpRecoGrammar::SetDictationStatefordictationorISpRecoGrammar::SetRuleStateorISpRecoGrammar::SetRuleIdStateforcommandandcontrol.Whenrecognitionscomebacktotheapplicationbymeansoftherequestednotificationmechanism,thelParammemberoftheSPEVENTstructurewillbeanISpRecoResultbywhichtheapplicationcandeterminewhatwasrecognizedandforwhichISpRecoGrammaroftheISpRecoContext.AnISpRecognizer,whethersharedorInProc,canhavemultipleISpRecoContextsassociatedwithit,andeachonecanbenotifiedinitsownwayofeventspertainingtoit.AnISpRecoContextcanhavemultipleISpRecoGrammarscreatedfromit,eachoneforrecognizingdifferenttypesofutterances.Backtotop

Application-LevelInterfacesThissectiondescribestheinterfacesandmethodsforincorporatingspeechintoapplications.TheyareintendedforuseattheAPIorapplicationlevel.SomemanagersorinterfacesmayhaveentriesalsoinEngine-LevelInterfacessection.However,entrieslistedhereapplyonlytotheapplicationlevel.

AudiointerfacesEventinginterfaces

GrammarCompilerinterfacesLexiconinterfaces

ResourceinterfacesSpeechRecognitioninterfaces

Text-to-Speechinterfaces

AudiointerfacesThissectionprovidesSAPI5audiointerfaces.AudioinheritsfromthestandardCOMIStreaminterface.SeetheMSDNdocumentationforacompletediscussionofIStreamandassociatedmethods.However,sincetheaudiodevicesrepresenthardware,::ClonemaybenotbeusedandwillreturnE_NOTIMPL.

ISpAudioISpMMSysAudioISpStream

ISpStreamFormatISpStreamFormatConverter

ThefollowinginterfacedoesnotinheritfromIStream:ISpTranscript

DevelopmentHelpers

HelperEnumerations,FunctionsandClasses DescriptionSPSTREAMFORMAT SAPIsupportedstreamformats.CSpEvent Classfordecodingeventstructures.CSpDynamicString Classformanagingdynamically

sizedWCHARstrings.SpBindToFile Functionconvertsthespecified

streamformatintoawaveformatstructure.

CSpStreamFormat ClassformanagingSAPIsupportedstreamformatsandWAVEFORMATEXstructures.

ISpAudioObjectsimplementingthisinterfacearereal-timeaudiostreams,suchasthoseconnectedtoalivemicrophoneortelephoneline.ISpAudiomethodssupportofcontrolofreal-timeaudiostreams.IStreamReadandWritemethodstransferdatatoorfromanobject.

WhentoImplementThisinterfaceshouldbeimplementedwhentheaudioinputoroutputsourceisnotastandardwindowsMultimediadevice.ItisexpectedtosupplyaninfiniteamountofdataandhenceitsstateshouldnotchangeexternallytoSAPI.Forthemajorityofusers,itwillnotbenecessarytoimplementanobjectprovidingthisinterface.Anexampleofwherethismightbeneededwouldbetoprovideatelephonyaudiodeviceortoperformechocancellationofaudiooutputontheinput.Telephoneapplicationprogramminginterface(TAPI)providesamechanismtotreatatelephonydeviceasaWindowsmultimediadeviceallowingtheuseoftheSAPIprovidedmultimediaaudioobjects.Ifthisimplementsarealtimeaudioinputoroutputobjectandrunsinadesktoporgraphicalenvironment,supportmaybeneededforvolume(seeSPDUI_AudioVolume)andaudioproperties(seeSPDUI_AudioProperties)UI.ThepreferredmethodforSAPItoimplementtheUIistohavetheobjectinheritfromISpTokenUI.Thiswillenableapplications(includingSpeechpropertiesinControlPanel)todisplaytheUIinasimpleandconsistentmanner.InordertopreventmultipleTTSvoicesorenginesfromspeakingsimultaneously,SAPIserializesoutputtoobjectswhichimplementtheISpAudiointerface.TodisableserializationofoutputstoanISpAudioobject,placeanattributecalled"NoSerializeAccess"intheAttributesfolderofitsobjecttoken.

ImplementedBySpMMAudioIn

SpMMAudioOut

MethodsinVtableOrder

Value DescriptionISpStreamFormatinterface

InheritsfromISpStreamFormatandallthosemethodsareaccessiblefromanISpAudioobject.

SetState Setsthestateoftheaudiodevice.SetFormat Setstheformatoftheaudiodevice.GetStatus Passesbackthestatusoftheaudio

device.SetBufferInfo Setstheaudiostreambuffer

information.GetBufferInfo Passesbacktheaudiostreambuffer

information.GetDefaultFormat Passesbackthedefaultaudioformat.EventHandle ReturnsaWin32eventhandlethat

applicationscanusetowaitforstatuschangesintheI/Ostream.

GetVolumeLevel Passesbackthecurrentvolumelevel.SetVolumeLevel Setsthecurrentvolumelevel.GetBufferNotifySize Retrievestheaudiostreambuffer

sizeinformation.SetBufferNotifySize Setstheaudiostreambuffersize

information.

DevelopmentHelpers

HelperEnumerations,FunctionsandClasses

Description

SPSTREAMFORMAT SAPIsupportedstreamformats.CSpStreamFormat ClassformanagingSAPIsupported

streamformatsandWAVEFORMATEXstructures.

ISpAudio::SetStateISpAudio::SetStatesetsthestateoftheaudiodevice.HRESULTSetState(SPAUDIOSTATENewState,ULONGLONGullReserved);

Parameters

NewState[in]TheflagoftypeSPAUDIOSTATEforthenewstateoftheaudiodevice.

ullReserved[in]Reserved,donotuse.Thisvaluemustbezero.

Returnvalues

Value DescriptionS_OK Functioncompleted

successfully.E_INVALIDARG ullReservedisnotzeroor

NewStateisnotoneoftheallowedvalues.

SPERR_DEVICE_BUSY Hardwaredeviceisinusebyanotherthreadorprocess.

SPERR_UNSUPPORTED_FORMAT CurrentformatsetbyISpAudio::SetFormatisnotsupportedbythehardwaredevice.

Remarks

WhentransitioningfromtheSPAS_CLOSEDstatetoanyotherstate,thecallershouldbereadytohandlevariouserrorconditions,specifically,SPERR_UNSUPPORTED_FORMATandSPERR_DEVICE_BUSY.Manymulti-mediadevicesdonotcorrectlyreporttheircapabilitiesforhandlingdifferentaudioformatsandfailonlywhenanattemptismadetoopenthedevice.Also,inmanyoldersystems,audiooutputdevicescanbeopenedonlybyasingleprocess.InallcurrentversionsofWindows,onlyasingleprocesscanopenanaudioinputdevice.Therefore,SPERR_DEVICE_BUSYwillreturnifanattemptismadetoopenadevicethatisbeingusedbyadifferentprocessorthread.Onsomeoldersoundcards,recordingandplaybackarenotpossiblesimultaneouslyoronlypossibleatthesamefrequency.Anapplicationmakinguseoftheinputandoutputaudioshouldbeawareofthisandinparticularattempttogracefullydegradefromhigherqualityfrequenciestothesamefrequencyforbothifthesoundcardmakesthisnecessary.Ingeneral,applicationsneednotchangethestateoftheaudiodevicedirectly.Withthesharedrecognizerinparticular,thiswilloftencauseunexpectedresults.SAPIwillautomaticallymanagethestateoftheaudiodevicebasedonthestateofallthegrammars,recognitioncontextsandtherecognizerinstance.

ISpAudio::SetFormatISpAudio::SetFormatsetstheformatoftheaudiodevice.HRESULTSetFormat(REFGUIDrguidFmtId,constWAVEFORMATEX*pWaveFormatEx);

Parameters

rguidFmtId[in]TheREFGUIDfortheformattoset.TypicallythiswillbeSPDFID_WaveFormatEx.ThisisrequiredfortheSAPImultimediaobjects.

pWaveFormatEx[in]AddressoftheWAVEFORMATEXstructurecontainingthewavefileformatinformation.

Returnvalues


successfully.Seenoteaboutsupportedformats.

E_INVALIDARG pWaveFormatExisinvalidorbad.

SPERR_DEVICE_BUSY DeviceisnotintheSPAS_CLOSEDstate.

SPERR_UNINITIALIZED Audiostreamnotinitialized.SPERR_UNSUPPORTED_FORMAT Specifiedformatisnot

supported.FAILED(hr) Appropriateerrormessage.

RemarksThismethodcanbecalledonlywhentheaudiodeviceisintheSPAS_CLOSEDstate.Notethatsuccessfullysettingtheformatonanaudiodevicedoesnotnecessarilymeanthattheformatissupported.Anattemptmustbemadetoplacethedeviceintoanon-closedstate(SPAS_STOP,SPAS_PAUSEorSPAS_RUN)tobesurethatthedevicecanhandletheformat.TheformatcanberetrievedbycallingtheISpStreamFormat::GetFormatmethod.ThehelperclassCSpStreamFormatandtheSPSTREAMFORMATenumerationcanbeusedtoavoidthepossibilityoftyposormistakeswhenfillingintheWAVEFORMATEXstructure.

ISpAudio::GetStatusISpAudio::GetStatuspassesbackthestatusoftheaudiodevice.Thismethoddetermineswhetherthedeviceisrunning,stopped,closed,orpaused.Italsodeterminesthesizeofanybuffereddata.HRESULTGetStatus(SPAUDIOSTATUS*pStatus);

Parameters

pStatus[out]PointertoanSPAUDIOSTATUSbuffertobefilledwiththestatusdetails.

Returnvalues


successfully.E_POINTER pStatusisinvalid.

ISpAudio::SetBufferInfoISpAudio::SetBufferInfosetstheaudiostreambufferinformation.HRESULTSetBufferInfo(constSPAUDIOBUFFERINFO*pBuffInfo);

Parameters

pBuffInfo[in]PointertotheSPAUDIOBUFFERINFObufferprovidingtherequestedsettings.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.SPERR_UNINITIALIZED Audiostreamnotinitialized.E_INVALIDARG pBuffInfoisinvalidortheparameters

donotmeetthecriteriadescribedabove.

SPERR_DEVICE_BUSY AudiodeviceisnotintheSPAS_CLOSEDstate.

FAILED(hr) Appropriateerrormessage.

RemarksThismethodcanbecalledonlywhentheaudiodeviceisintheSPAS_CLOSEDstate.TheSPAUDIOBUFFERINFOmembersmustconformtothefollowingrestrictions:

SPAudioBufferInfo.ulMsMinNotificationcannotbelargerthanonequarterthesizeofSPAudioBufferInfo.ulMsBufferSizeand

mustnotbezero.SPAudioBufferInfo.ulMsEventBiascannotbelargerthanSPAudioBufferInfo.ulMsBufferSize.SPAudioBufferInfo.ulMsBufferSizemustbegreaterthanorequalto200milliseconds.

ISpAudio::GetBufferInfoISpAudio::GetBufferInfopassesbacktheaudiostreambufferinformation.HRESULTGetBufferInfo(SPAUDIOBUFFERINFO*pBuffInfo);

Parameters

pBuffInfo[out]PointertotheSPAUDIOBUFFERINFObuffer.

Returnvalues


successfully.E_POINTER pBuffInfoisinvalid.

ISpAudio::GetDefaultFormatISpAudio::GetDefaultFormatpassesbackthedefaultaudioformat.HRESULTGetDefaultFormat(GUID*pFormatId,WAVEFORMATEX**ppCoMemWaveFormatEx);

Parameters

pFormatId[out]PointertotheGUIDofthedefaultformat.

ppCoMemWaveFormatEx[out]AddressofapointertotheWAVEFORMATEXstructurethatreceivesthewavefileformatinformation.SAPIallocatesthememoryfortheWAVEFORMATEXdatastructureusingCoTaskMemAlloc,butitisthecaller'sresponsibilitytocallCoTaskMemFreeonthereturnedWAVEFORMATEXpointer.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.SPERR_UNINITIALIZED Streamisuninitialized.E_POINTER pFormatIdisinvalid.

RemarksOtherformatsmaybesupportedbytheaudiodevice;however,thisformatisguaranteedtowork.Oldersoundcardscanpotentiallyfailwhenattemptingtousethisformatiftheyarenotfullyduplexordonotsupportfullduplexoperationat

differentfrequencies.Anapplicationshouldattempttodegradegracefullywhenthisoccurs.

ISpAudio::EventHandleISpAudio::EventHandlereturnsaWin32eventhandlethatapplicationscanusetowaitforstatuschangesintheI/Ostream.HANDLEEventHandle(void);

ParametersNone

Returnvalues

Value DescriptionHANDLE Returnsvalidevent

handle.

RemarksThehandlemayuseoneofthevariousWin32waitfunctions,suchasWaitForSingleObjectorWaitForMultipleObjects.Forreadstreams,settheeventwhenthereisdataavailabletoreadandresetitwheneverthereisnoavailabledata.Forwritestreams,settheeventwhenallofthedatahasbeenwrittentothedevice,andresetitatanytimewhenthereisstilldataavailabletobeplayed.Thecallershouldnotclosethereturnedhandle,norshouldthecallereverusetheeventhandleaftercallingRelease()ontheaudioobject.Theaudiodevicewillclosethehandleonthefinalreleaseoftheobject.

ISpAudio::GetVolumeLevelISpAudio::GetVolumeLevelpassesbackthecurrentvolumelevel.Thevolumelevelisonalinearscalefromzeroto10000.HRESULTGetVolumeLevel(ULONG*pLevel);

Parameters

pLevel[out]Pointertothereturnedvolumelevel.

Returnvalues


successfully.SPERR_UNINITIALIZED Audiointerfaceisnot

initialized.SPERR_DEVICE_NOT_SUPPORTED Thedeviceisnotvalidor

doesnotsupportvolumes.E_POINTER pLevelisinvalidorbad.FAILED(hr) Appropriateerrormessage.

RemarksForinputdeviceswithaboostcontrolforthemicrophone,SAPIwillsplitthevolumerangeintotwotoallowautomateduseoftheboost.Theboostwillbeofffromzeroto4999andonfrom5000to10,000.Ineachrange,thefullvolumerangeofthedevicewillbeusedindependently.Thiscanleadtodiscontinuityintheinputenergylevelforaconstantvolumesoundsource.

Onsomesoundcards,theboostisappliedtotheinputvolume,butonothers,theboostisappliedtotheplaybackvolumeresultinginthetworangesbehavingidenticallybecausetheinputlevelisunaffected.Microphonewizardsdeterminingthebestvolumeinputlevelshouldtakeintoconsiderationthepotentialdiscontinuityandensurethatthealgorithmusedtoadjusttheinputvolumelevelcanhandlethevariouspossibleformsofdiscontinuityat5,000Fordeviceswithoutaboost,thereisnodiscontinuityat5000.

ISpAudio::SetVolumeLevelISpAudio::SetVolumeLevelsetsthecurrentvolumelevel.Itisonalinearscalefromzeroto10000.HRESULTSetVolumeLevel(ULONGLevel);

Parameters

Level[in]Thenewvolumelevel.

Returnvalues


successfully.E_INVALIDARG Levelisgreaterthan10,000.SPERR_DEVICE_NOT_SUPPORTED Thedeviceisnotvalidor

doesnotsupportvolumes.FAILED(hr) Appropriateerrormessage.

RemarksForinputdeviceswithaboostcontrolforthemicrophone,SAPIwillsplitthevolumerangeintotwotoallowautomateduseoftheboost.Theboostwillbeofffromzeroto4,999andonfrom5,000to10,000.Ineachrange,thefullvolumerangeofthedevicewillbeusedindependently.Thiscanleadtodiscontinuityintheinputenergylevelforaconstantvolumesoundsource.Onsomesoundcards,theboostisappliedtotheinputvolume,butonothers,theboostisappliedtotheplaybackvolumeresultinginthetworangesperformingidenticallybecausethe

inputlevelisunaffected.Microphonewizardsdeterminingthebestvolumeinputlevelshouldtakeintoconsiderationthepotentialdiscontinuityandensurethatthealgorithmusedtoadjusttheinputvolumelevelcanhandlethevariouspossibleformsofdiscontinuityat5,000Fordeviceswithoutaboost,thereisnodiscontinuityat5,000.

ISpAudio::GetBufferNotifySizeISpAudio::GetBufferNotifySizeretrievestheaudiostreambuffersizeinformation.ThisinformationisusedtodeterminewhentheeventreturnedbyISpAudio::EventHandleissetorreset.HRESULTGetBufferNotifySize(ULONG*pcbSize);

Parameters

pcbSize[out]Addressofthesizeinformation,specifiedinbytes,thatisassociatedwiththeaudiostreambuffer.

Returnvalues


successfully.E_POINTER Invalidpointer.

RemarksForreadstreams,theeventissetiftheaudiobufferedisgreaterthanorequaltothevaluesetinpcbSize,otherwisetheeventinformationisreset.Forwritestreams,theeventissetiftheaudiobufferedislessthanthevaluesetinpcbSize,otherwisetheeventinformationisreset.

ISpAudio::SetBufferNotifySizeISpAudio::SetBufferNotifySizesetstheaudiostreambuffersizeinformation.ThisinformationisusedtodeterminewhentheeventreturnedbyISpAudio::EventHandleissetorreset.HRESULTSetBufferNotifySize(ULONGcbSize);

Parameters

cbSize[in]Thesize,specifiedinbytes,oftheinformationassociatedwiththeaudiostreambuffer.

Returnvalues


successfully.FAILED(hr) Appropriateerrormessage.

RemarksForreadstreams,theeventissetiftheaudiobufferedisgreaterthanorequaltothevaluesetincbSize,otherwisetheeventinformationisreset.Forwritestreams,theeventissetiftheaudiobufferedislessthanthevaluesetincbSize,otherwisetheeventinformationisreset.

ISpMMSysAudioThisistheinterfacetotheaudioimplementationforthestandardWindowsmultimedialayer(waveinandwaveout).AudioobjectscreatedthroughanobjecttokendonotallowISpMMSysAudio::SetDeviceIdtoworkbecausethetokenspecifieswhichaudiodeviceIDtouse.IfanapplicationwantstoassociateanaudioobjectwithaspecificmultimediawaveinorwaveoutdeviceID,itshoulduseCoCreateInstancewithCLSID_SpMMAudioOutorCLSID_SpMMAudioInandthenusetheISpMMSysAudio::SetDeviceIdmethodtoselectthedevice.Innormalapplicationdevelopment,thiswillnotbenecessaryfortworeasons:

Desktopapplicationswillgenerallyusethesharedrecognizerinstancewhichautomaticallyusesthedefaultaudiodevice.Thiscannotbechanged.

FortheInProcrecognizerinstance,tokensexistforthequickcreationofthecorrectSpMMAudioInorSpMMAudioOutforallofthemultimediadevicesonthesystem.

Forinputdevices,SAPIwillattempttoautomaticallyidentifythemicrophonelineontheinputdevice.Onnon-EnglishversionsofWindowsandonasmallnumberofEnglishsystems,itmaynotbepossibleforSAPItoautomaticallydetectthecorrectmicrophoneline.Inthiscase,noerrorwillbedetectedorreturned.Insuchcases,ifspeechinputisnotcorrectlydetected,theusermustsetthemicrophoneinputlinedirectlyusingSpeechpropertiesinControlPanel-->SpeechRecognitiontab-->AudioInputSettings-->Properties.Inparticular,itmaybenecessarytoadjustthemicrophoneinputlineusedondeviceswithmultiplemicrophoneinputssuchastheSoundBlasterLivePlatinumbecausethedefaultinputlinemaynotbetheinputpreferredbytheuser.

ImplementedBy

SpMMAudioInSpMMAudioOut


ISpMMSysAudioMethods DescriptionISpStreamFormatinterface

InheritsfromISpStreamFormatandallmethodsareaccessiblefromanISpMMSysAudioobject.

ISpAudiointerface InheritsfromISpAudioandallmethodsareaccessiblefromanISpMMSysAudioobject.

GetDeviceId PassesbackthemultimediadeviceIDbeingusedbytheaudioobject.

SetDeviceId SetsthemultimediadeviceID.GetMMHandle Passesbackamultimediaaudio

streamhandle.GetLineId Retrievesthelineidentifier

associatedwiththemultimediadevice.

SetLineId Setsthelineidentifierassociatedwiththemultimediadevice.

IStreamfunctionsasinheritedfromISpAudio

PleaseseetheMicrosoft®PlatformSoftwareDevelopmentKit(PSDK)foracompletedescriptionoftheIStreaminterface.

IStreamMethods DescriptionRead Readsdatafromthemultimedia

audiodevice.Write Writesdatatothemultimediaaudio

device.Seek Retrievesonlythecurrentdevice

http://go.microsoft.com/fwlink/?linkid=400&clcid=0x409

positionbecausemultimediadevicesrepresenthardware.

SetSize Notusedbecausemultimediadevicesrepresenthardware.

CopyTo Copiesaspecifiednumberofbytesfromthecurrentseekpointerinthestreamtothecurrentseekpointerinanotherstream.

Commit Updatesdevicestateandcommitbuffereddata.SAPIwillautomaticallymanagedevicestateandbuffereddata,sothatthedeveloperisnotexpectedtocallthismethod.

Revert ReturnsE_NOTIMPLbecausemultimediadevicesrepresenthardware.

LockRegion ReturnsE_NOTIMPLbecausemultimediadevicesrepresenthardware.

UnlockRegion ReturnsE_NOTIMPLbecausemultimediadevicesrepresenthardware.

Stat Retrievesthecurrentdeviceposition.

Clone ReturnsE_NOTIMPLbecausemultimediadevicesrepresenthardware.

ISpMMSysAudio::ReadISpMMSysAudio::Readreadsthedatafromthemultimediaaudiodevice.Theaudiodeviceshouldnotbedirectlymanipulatedwhenperformingspeechrecognition(seeISpRecognizer).

HRESULTRead(void*pv,ULONGcb,ULONG*pcbRead);

Parameters

pv[in]Pointertothebufferintowhichthestreamdataisread.Ifanerroroccurs,thisvalueisNULL.

cb[in]Specifiesthenumberofbytesofdatatoattempttoreadfromtheaudiodevice.

pcbRead[out]PointertoaULONGvariablethatreceivestheactualnumberofbytesreadfromthestreamobject.IfsettoNULL,nobytevalueispassedback.

Returnvalues


successfully.

SPERR_AUDIO_BUFFER_OVERFLOW SAPI'sinternalaudiobufferhasfilled,andthedevicehasbeenclosed.SeeRemarkssection.

SPERR_AUDIO_BUFFER_UNDERFLOW Themultimediaobjecthasnotreceivedaudiodatafromthedevicequicklyenough,andthedevicehasbeenclosed.SeeRemarkssection.

SPERR_AUDIO_STOPPED Multimediadevicestatehasbeensettostopped.

E_OUTOFMEMORY Exceededavailablememory

E_POINTER AtleastoneofpcbReadorpvareinvalidorbad.

STG_E_ACCESSDENIED Multimediadeviceisread-onlyandnobyteswillberead.Errorwilloccurwhenreadingfromanoutputdevice.


RemarksaboutaudiobufferoverflowsandunderflowsSAPIautomaticallystoresdatainabufferbeforeitisreadfromthedevice.BufferingtheaudiodataensuresthatapplicationsandSAPI-compliantspeechrecognitionengineswillnotlosereal-timeaudiodata.AnerrantapplicationorspeechrecognitionenginethatdoesnotcallReadoftenenoughcouldfrequentlyfilltheaudiobuffer.Toensurethatlargeamountsofsystemmemoryarenotfilled,SAPIlimitsthebuffersizeto30timestheaveragebytesper

second(WAVEFORMATEX->nAvgBytesPerSec)-approximately30seconds.Iftheaudiobufferisfilled,SAPIwillautomaticallysetthedevicestatetoSPAS_CLOSED(seeSPAUDIOSTATE)andreturnabufferoverflowerror(i.e.,SPERR_AUDIO_BUFFER_OVERFLOW)whenISpMMSysAudio::Readiscalled.Anerrantmultimediadevice(and/ordriver)thatdoesnotreturnaudiodataquicklyenoughcouldgreatlyreducethespeedofaspeechapplicationorSRengine.TopreventthedegradationofapplicationorSRengineperformance,SAPIrequiresthatthemultimediadevicereturndataatleastonceeveryfiveseconds.Iftheaudioisnotreturnedbeforefiveseconds,SAPIwillautomaticallysetthedevicestatetoSPAS_CLOSED(seeSPAUDIOSTATE)andreturnabufferunderflowerror(i.e.,SPERR_AUDIO_BUFFER_UNDERFLOW)whenISpMMSysAudio::Readiscalled.Applicationsshouldmanuallyreopentheaudiodevice(seeISpAudio::SetState)topreventlosinginputdatathatcouldimpacttheuser.ForSRengines,SAPIautomaticallyattemptstorestartthemultimediadeviceaftertheSRengineexitsISpSREngine::RecognizeStream.

ISpMMSysAudio::WriteISpMMSysAudio::Writewritesdatatothemultimediaaudiodevice.Theaudiodeviceshouldnotbedirectlymanipulatedwhenperformingspeechrecognition(seeISpRecognizer).

HRESULTWrite(constvoid*pv,ULONGcb,ULONG*pcbWritten);

Parameters

pv[in]Pointertothebuffercontainingthedatathatistobewrittentotheaudiodevice.Avalidpointermustbeprovidedforthisparameterevenwhencbiszero.

cb[in]Thenumberofbytesofdatatoattempttowritetotheaudiodevice.Thisvaluemaybezero.

pcbWritten[out]PointertoaULONGvariablewherethismethodwritestheactualnumberofbyteswrittentotheaudiodevice.IfsettoNULL,nobytevalueispassedback.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.

SPERR_AUDIO_STOPPED Multimediadevicehasbeenstopped.E_OUTOFMEMORY Exceededavailablememory.E_POINTER AtleastoneofpcbWrittenorpvare

invalidorbad.STG_E_ACCESSDENIED Multimediadeviceiswrite-onlyand

nobyteswillbewritten.Errorwilloccurwhenwritingtoaninputdevice.


ISpMMSysAudio::GetDeviceIdISpMMSysAudio::GetDeviceIdpassesbackthemultimediadeviceIDbeingusedbytheaudioobject.HRESULTGetDeviceId(UINT*puDeviceId);

Parameters

puDeviceId[out]PointerreceivingthedeviceID.

Returnvalues


successfully.E_POINTER puDeviceIdisabadpointer.

RemarksThedefaultdeviceIDforSpMMSysAudioobjectsthatarecreatedusingCoCreateInstanceistheWAVE_MAPPER.Foraudioobjectscreatedusinganobjecttoken,theIDwillalwaysbeaspecificwaveinorwaveoutdeviceID.

ExampleThefollowingcodesnippetillustratestheuseofISpMMSysAudio::GetDeviceIdusingCoCreateInstance.HRESULThr=S_OK;

//createthemultimediainputobjecthr=cpMMSysAudio.CoCreateInstance(CLSID_SpMMAudioIn);//Checkhr

//getthedefaultdeviceidUINTuiDeviceId;hr=cpMMSysAudio->GetDeviceId(&uiDeviceId);//Checkhr

//uiDeviceId==WAVE_MAPPER

ThefollowingcodesnippetillustratestheuseofISpMMSysAudio::GetDeviceIdusinganISpObjectTokenHRESULThr=S_OK;

//getthecurrentmultimediaobject'sobjecttokenhr=cpMMSysAudio.QueryInterface(&cpObjectWithToken);//Checkhr

//Findthepreferredmultimediaobjecttokenhr=SpFindBestToken(SPCAT_AUDIOIN,L"Technology=MMSys",NULL,&cpObjectToken);//Checkhr

//setthecurrentmultimediaobjecttothepreferredmultimediaobjecttokenhr=cpObjectWithToken->SetObjectToken(cpObjectToken);//Checkhr

//getthedeviceidfortheobjectUINTuiDeviceId;hr=cpMMSysAudio->GetDeviceId(&uiDeviceId);//Checkhr

//uiDeviceId!=WAVE_MAPPER

ISpMMSysAudio::SetDeviceIdISpMMSysAudio::SetDeviceIdsetsthemultimediadeviceID.HRESULTSetDeviceId(UINTuDeviceId);

Parameters

uDeviceId[in]ThedeviceIDofthedevicetoset.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.SPERR_DEVICE_BUSY ObjectisnotintheSPAS_CLOSED

state.SPERR_ALREADY_INITIALIZEDObjectwascreatedusingan

objecttoken.E_INVALIDARG uDeviceIdisinvalid.Itisnotset

toWAVE_MAPPERordevicedoesnotexist.

RemarksThismethodworksonlyonaudioobjectsthatwerenotcreatedusinganobjecttoken,andonlywhentheobjectisintheSPAS_CLOSEDstate.Thismethodshouldnotbeusedinnormalapplicationdevelopment.SAPIprovidestokensforalltheavailablesounddevicesinacomputerandthesecanbeusedtocreateaninitializedSpMMSysAudioobject.Thismethodisavailablefornon-standardmultimediaaudiodevices.SeetheSimpleTelephonysampleforanexampleofwhenthismethodis

useful.

ExampleThefollowingcodesnippetillustratestheuseofISpMMSysAudio::SetDeviceId.HRESULThr=S_OK;

//createthemultimediaoutputobjecthr=cpMMSysAudio.CoCreateInstance(CLSID_SpMMAudioOut);//Checkhr

//settheoutputdevicetoanalternatemultimediadevice(e.g.modem)hr=cpMMSysAudio->SetDeviceId(ALTERNATE_MM_DEVICE);//Checkhr

ISpMMSysAudio::GetMMHandleISpMMSysAudio::GetMMHandlepassesbackamultimediaaudiodevicestreamhandle.HRESULTGetMMHandle(void**pHandle);

Parameters

pHandleThewaveinorwaveoutdevicehandle.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_POINTER pHandleisinvalid.SPERR_UNINITIALIZED AudioobjectisintheSPAS_CLOSED

state.

RemarksTheaudioobjectmustnotbeintheSPAS_CLOSEDstateorthiscallwillfailbecausethemultimediadevicewillnothavebeenopenedyet.Thecallermustnotclosethepassedbackhandle.ThecallermustnotusethehandleeitherafterchangingthestateoftheaudioobjecttoSPAS_CLOSEDorafterreleasingtheobject.

ISpMMSysAudio::GetLineIdISpMMSysAudio::GetLineIdretrievesthecurrentlineidentifierassociatedwiththemultimediadevice.Mixerlinesarenotsupportedforoutputdevices.HRESULTGetLineId(UINT*puLineId);

Parameters

puLineId[out]Addressofthestructurethatreceivesthelineidentifierinformation.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_NOTIMPL Notimplementedforoutputdevices.E_POINTER puLineIdisinvalid.SPERR_NOT_FOUND Theaudiodevicemusthavebeen

createdfromatoken.FAILED(hr) Appropriateerrormessage.

RemarksFormoreinformationontheusesofdevicelines,pleaseseetheWin32multimediamixerAPI(e.g.,mixerOpen,mixerGetId,mixerGetLineInfo,etc.)Forinputdevices,SAPIwillattempttoautomaticallyidentifythemicrophonelineontheinputdevice.Onnon-EnglishversionsofWindowsandonasmallnumberofEnglishsystems,itmaynot

bepossibleforSAPItoautomaticallydetectthecorrectmicrophoneline.Inthiscase,noerrorwillbedetectedorreturned.Insuchcases,ifspeechinputisnotcorrectlydetected,theusermustsetthemicrophoneinputlinedirectlyusingControlPanel-->Speechproperties-->SpeechRecognitiontab-->AudioSettings-->Properties.Inparticular,thismaybenecessarytoadjustthemicrophoneinputlineusedondeviceswithmultiplemicrophoneinputssuchastheSoundBlasterLivePlatinumastheautomaticallychosenlinemaynotbetheinputpreferredbytheuser.

ISpMMSysAudio::SetLineIdISpMMSysAudio::SetLineIdsetsthelineidentifierassociatedwiththemultimediadevice.Mixerlinesarenotsupportedforoutputdevices.HRESULTSetLineId(UINTuLineId);

Parameters

uLineId[in]Valuespecifyingthelineidentifierinformation.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_INVALIDARG ThespecifieduLineIdisnotsupported

onthecurrentdevice.SPERR_NOT_FOUND Theaudiodevicemusthavebeen

createdfromatoken.E_NOTIMPL Notimplementedforoutputdevices.FAILED(hr) Appropriateerrormessage.

RemarksFormoreinformationontheusesofdevicelines,pleaseseetheWin32multimediamixerAPI(e.g.,mixerOpen,mixerGetId,mixerGetLineInfo,etc.)Forinputdevices,SAPIattemptstoautomaticallyidentifythemicrophonelineontheinputdevice.Onnon-EnglishversionsofWindowsandonafewEnglishsystems,itmaynotbepossible

forSAPItoautomaticallydetectthecorrectmicrophoneline.Inthiscase,noerrorwillbedetectedorreturned.Ifspeechinputisnotcorrectlydetected,theusermustsetthemicrophoneinputlinedirectlyusingControlPanel-->Speechproperties-->SpeechRecognitiontab-->AudioSettings-->Properties.ItmaybenecessarytoadjustthemicrophoneinputlineusedondeviceswithmultiplemicrophoneinputssuchastheSoundBlasterLivePlatinum.Inthesecases,theautomaticallychosenlinemaynotbetheinputpreferredbytheuser.

ISpStreamThisinterfaceprovidestwodistinctfunctions:

TheapplicationdevelopercanwrapanexistingstreamupbyprovidingbothanIStreamanditsformatsothattheunderlyingISpStreamFormatcanprovidethisdatatoSAPIwhenrequired.ThenewISpStreamobjectcanbeusedasaninputforSAPIwhereverSAPIrequiresanISpStreamFormat.ISpStreamcreatesanobjectfromafilesuitableforSAPIusageusingBindToFile.ThehelperfunctionSPBindToFilemayalsobeusedtosimplifythisprocessevenfurther.

ImplementedBySpStream


ISpStreamMethods DescriptionSetBaseStream Setsthebaseaddressoftheaudio

stream.GetBaseStream Retrievesthebaseaddressofthe

audiostream.BindToFile Bindstheaudiostreamtothefile

thatitidentifies.Close Closestheaudiostream.

DevelopmentHelpers

HelperEnumerations,FunctionsandClasses DescriptionSPSTREAMFORMAT SAPIsupportedstreamformatsCSpStreamFormat ClassformanagingSAPIsupported

streamformatsandWAVEFORMATEXstructures

ISpStream::SetBaseStreamISpStream::SetBaseStreaminitializestheISpStreamobjectwiththeformatoftheIStreamandanobjecttoencapsulate.HRESULTSetBaseStream(IStream*pStream,REFGUIDrguidFormat,constWAVEFORMATEX*pWaveFormatEx);

Parameters

pStreamAddressoftheIStreamcontainingthebasestreamdata.

rguidFormatThedataformatidentifierassociatedwiththestream.

pWaveFormatExAddressoftheWAVEFORMATEXstructurethatcontainsthewavefileformatinformation.IfguidFormatIdisSPDFID_WaveFormatEx,thismustpointtoavalidWAVEFORMATEXstructure.Forotherformats,itshouldbeNULL.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_INVALIDARG Oneormoreparametersare

invalid.SPERR_ALREADY_INITIALIZED Theobjecthasalreadybeen

initialized.


Remarks

ThehelperclassCSpStreamFormatandtheSPSTREAMFORMATenumerationcanbeusedtoavoidthepossibilityoftyposormistakeswhenfillingintheWAVEFORMATEXstructure.

ISpStream::GetBaseStreamISpStream::GetBaseStreamretrievestheencapsulatedIStreamobjectforaninstanceoftheISpStreamobject.HRESULTGetBaseStream(IStream**ppStream);

Parameters

ppStreamAddressofapointertotheencapsulatedIStreamthatcontainsanaudiostreamortextstream.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_POINTER TheppStreampointerisinvalidor

bad.SPERR_STREAM_CLOSED Thestreamisclosedorunavailable.S_FALSE TheISpStreaminstancehasnotbeen

initializedwithanIStream.

ISpStream::BindToFileISpStream::BindToFilebindstheinputstreamtothefilethatitidentifies.HRESULTBindToFile(constWCHAR*pszFileName,SPFILEMODEeMode,constGUID*pguidFormatId,constWAVEFORMATEX *pWaveFormatEx,ULONGLONGullEventInterest);

Parameters

pszFileNameAddressofanull-terminatedstringcontainingthefilenameofthefiletobindthestreamto.

eModeFlagofthetypeSPFILEMODEtodefinethefileopeningmode.Whenopeninganaudiowavefile,eModemustbeSPFM_OPEN_READONLYorSPFM_CREATE_ALWAYS,otherwisethecallwillfail.

pguidFormatIdThedataformatidentifierassociatedwiththestream.ThiscanbeNULLandtheformatwillbedeterminedfromthesuppliedwavefile,ifthefilehasthewavextension.Ifitdoesnot,thefileisassumedtobeatextfile.

pWaveFormatExAddressoftheWAVEFORMATEXstructurethatcontainsthewavefileformatinformation.IfguidFormatIdis

SPDFID_WaveFormatEx,thismustpointtoavalidWAVEFORMATEXstructure.Forotherformats,itshouldbeNULL.

ullEventInterestFlagsoftypeSPEVENTENUMfortheformatconvertertowatch.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_INVALIDARG Atleastoneofthefollowingwas

encountered.pszFileNameorpguidFormatIdisinvalidorbad;eModeexceedsSPFM_CREATE_ALWAYS;anoperationcouldnotbecompleted.

E_OUTOFMEMORY Exceededavailablememory.STG_E_FILENOTFOUND FilepszFileNamedoesnotexist.SPERR_ALREADY_INITIALIZED Theobjecthasalreadybeen

initialized.FAILED(hr) Appropriateerrormessage.

RemarksInspeechrecognition,::BindToFilesupportsonlywaveaudiofiles.ItpassesSAPIanaudiofiletopasstotheengine.Intext-to-speech,::BindToFilesupportsbothaudioandtextfiles.SeeISpVoice::SpeakStreamformoreinformation.ThehelperclassCSpStreamFormatandtheSPSTREAMFORMATenumerationcanbeusedtoavoidthepossibilityoftyposormistakeswhenfillingintheWAVEFORMATEXstructure.

ExampleThefollowingcodesnippetillustratestheuseofISpStream::BindToFileforcreatingawritablewavefileHRESULThr=S_OK;

//createthestreamobjecthr=cpSpStream.CoCreateInstance(CLSID_SpStream);//Checkhr

//createastreamformathelperfor22khzm16-bit,monowavestreamCSpStreamFormatFmt(SPSF_22kHz16BitMono,&hr);//Checkhr//createthenewstreamanditscorrespondingfileontheharddisk//NOTE:Specifythefileformatwhencreatingthefilehr=cpSpStream->BindToFile(WAVE_FILENAME,SPFM_CREATE_ALWAYS,&Fmt.FormatId(),Fmt.WaveFormatExPtr(),NULL);//Checkhr

//writesomedatatothestreamhr=cpSpStream->Write(WAVE_DATA_CHUNK,SIZEOF_WAVE_DATA_CHUNK,&cbWritten);//Checkhr

ThefollowingcodesnippetillustratestheuseofISpStream::BindToFileforcreatingaread-onlywavefileHRESULThr=S_OK;

//createthestreamobjecthr=cpSpStream.CoCreateInstance(CLSID_SpStream);//Checkhr//createanewstream,byopeningawavefilefromtheharddisk//NOTE:Sinceanexistingfileisbeingread,SAPIwillreadthewavestreamformatautomaticallyhr=cpSpStream->BindToFile(WAVE_FILENAME,SPFM_OPEN_READONLY,NULL,NULL,NULL);//Checkhr

//readsomedatafromthestreamhr=cpSpStream->Read(&bData,SIZEOF_WAVE_DATA_CHUNK,&cbWritten);//Checkhr

ISpStream::CloseISpStream::Closeclosestheaudiostreamandvalidatesthecloseoperation.HRESULTClose(void);

ParametersNone.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.SPERR_STREAM_CLOSED Thestreamisclosedorunavailable.FAILED(hr) Appropriateerrormessage.

RemarksReleasingtheISpStreamobjectwillautomaticallycallthismethod.However,anyerrorsencounteredwillnotbesentasnotificationstotheapplication.Hencetheapplicationcanexplicitlycallthismethodfirsttocheckthatnoerrorsoccurredduringthecloseoperation.

ISpStreamFormatISpStreamFormatinheritsfromIStream.ThisistheminimumextrainterfacerequiredbySAPIinadditiontotheIStreaminterface.Usingthisinterface,SAPIcanquerythestreamtodeterminetheformatofthestreamdata.AlmostallSAPIfunctionsrequiringorreturningastreamwillrequireorreturnanISpStreamFormat.

WhentoImplementThisinterfaceshouldbeimplementedwhenimplementingastreamfromscratch.IfanIStreamalreadyexists,SAPIcanuseitwiththeprovidedISpStreamobject.Innormalusage,thisinterfacedoesnotneedtobeimplemented.

ImplementedBySpMMAudioIn

SpMMAudioOutSpStreamFormatConverter

SpStream


ISpStreamFormatMethods DescriptionGetFormat Passesbackthecachedformatof

thestream.

DevelopmentHelpers

HelperEnumerations,FunctionsandClasses Description

SPSTREAMFORMAT SAPIsupportedstreamformatsCSpStreamFormat ClassformanagingSAPIsupported


ISpStreamFormat::GetFormatISpStreamFormat::GetFormatpassesbackthecachedformatofthestream.SAPIusesthisdatatodeterminehowtohandlethestreamdatapresentintheunderlyingIStream.HRESULTGetFormat(GUID*pguidFormatId,WAVEFORMATEX**ppCoMemWaveFormatEx);

Parameters

pguidFormatIdAddressofapointertoGUIDdataobjectthatreceivestheformatofthestreambeingused.ThisistypicallyeitherSPDFID_TextorSPDFID_WaveFormatEx.

ppCoMemWaveFormatExAddressofapointertoaWAVEFORMATEXdatastructurethatreceivesthewavefileformatinformation.ThisisonlyapplicablewhenthereturnGUIDisSPDFID_WaveFormatEx.SAPIallocatesthememoryfortheWAVEFORMATEXdatastructureusingCoTaskMemAlloc,butitisthecaller'sresponsibilitytocallCoTaskMemFreeonthereturnedWAVEFORMATEXpointer.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_POINTER Pointerislocatingamemoryblock

thatisNULLoreithertoosmalloris

notwritable.SPERR_UNINITIALIZED Theobjecthasnotbeenproperly

initialized.SPERR_STREAM_CLOSED Thestreamisclosedorunavailable.

ISpStreamFormatConverterISpStreamFormatConverteristheprimaryinterfaceimplementedbytheSAPIaudiodataformatconverter.SAPIusestheformatconvertertocompensatefordifferencesbetweensupportedSRandTTSengineformats,andtheI/Oformatsrequestedbytheapplication.Typicallyapplicationsandenginesdonotusethisobjectdirectly.Theformatconverterisawrapperobjectthatencapsulatesthespecifiedbasestream.Itperformsconversionontheflyduringread/writeoperations.TheWindowsACM(AudioCompressionManager)layerperformstheconversion.SeveralmethodsareincludedinadditiontotheISpStreamFormatinterfacetoallowdataconversion.

ImplementedBySpStreamFormatConverter

RemarksSAPIutilizesthehostsystem'sinstalledaudiocodecstoperformtheconversion.SAPIcurrentlysupports1-stageand2-stagestreamconversions,butdoesnotsupport3-or-more-stageconversions.Anexampleofa1-stagestreamformatconversionistheconversionofaPCMformattoanotherPCMformat(e.g.,8kHz16-bitStereoPCM[SPSF_8kHz16BitStereo]->44kHz8-bitMono[SPSF_44kHz8BitMono]).Thisrequiresonlyonecodec(e.g.,"MicrosoftPCMConverter").Anexampleofa2-stagestreamconversionistheconversionofacompressedformattoaPCMformat(e.g.,TrueSpeech8kHz1-BitMono[SPSF_TrueSpeech_8kHz1BitMono]->8kHz8-bitMonoPCM[SPSF_8kHz8BitMono]->44kHz16-bitStereo[SPSF_44kHz16BitStereo]).Thisrequirestwocodecs(e.g.,"DSP

GroupTrueSpeech(TM)Audio"and"MicrosoftPCMConverter").NotethatoneoftheformatsmustbeaPCMformat.Anexampleofanunsupported3-stagestreamconversionistheconversionofacompressedformattoanothercompressedformat(e.g.,TrueSpeech8kHz1-BitMono[SPSF_TrueSpeech_8kHz1BitMono]->8kHz8-bitMonoPCM[SPSF_8kHz8BitMono]->8kHz8-bitStereoPCM[SPSF_8kHz8BitStereo]->ALaw8kHzStereo[SPSF_CCITT_ALaw_8kHzStereo]).Thiswouldrequirethreecodecs(e.g.,"DSPGroupTrueSpeech(TM)Audio","MicrosoftPCMConverter",and"MicrosoftCCITTG.771Audio").NotethatSAPIiscapableofconvertingbetweentwocompressednon-PCMformatsifasinglecodeccandotheentireconversion.


ISpStreamFormatConverterMethods DescriptionISpStreamFormatinterface InheritsfromISpStreamFormat

andallthosemethodsareaccessiblefromanISpStreamFormatConverterobject.

SetBaseStream Setsaudiostreamtobewrappedbytheformatconverter.

GetBaseStream Getsthebaseaudiostreamthatisbeingwrapped.

SetFormat Setstheconversion(output)format.

ResetSeekPosition Resetstheformatconverter'sstreamseekpositiontothestartofthestream.

ScaleConvertedToBaseOffsetMapsanoffsetintheconvertedstreamintoan

offsetinthebasestream.ScaleBaseToConvertedOffsetMapsanoffsetinthebase

streamintoanoffsetintheconvertedstream.

DevelopmentHelpers

HelperEnumerations,FunctionsandClasses DescriptionSPSTREAMFORMAT SAPIsupportedstreamformatsCSpStreamFormat ClassformanagingSAPIsupported


ISpStreamFormatConverter::SetBaseStreamISpStreamFormatConverter::SetBaseStreamsetsanaudiostreamtobewrappedbytheformatconverter.Theformatconverterisastreamobjectthatencapsulatesthebasestreamandperformsformatconversionontheflyduringread/writeoperations.HRESULTSetBaseStream(ISpStreamFormat*pStream,BOOLfSetFormatToBaseStreamFormat,BOOLfWriteToBaseStream);

Parameters

pStream[in]Thestreamtobewrapped.IfNULL,thecurrentbasestreamisreleasedandanyassociatedresourcesarereleased.

fSetFormatToBaseStreamFormat[in]Flagspecifiesthattheconverter'sstreamformatwillbesettothesameformatasthebasestream(setupasapassthrough).IfpStream==NULLandthisissettoTRUE,theformatconverter'sstreamformatisresettobeundefined.

fWriteToBaseStream[in]IfTRUE,datawillbewrittentothebasestream.IfFALSE,datawillbereadfromthebasestream.TheformatconvertercanonlybeinoneI/Omodeortheotheratatime.

Returnvalues


successfully.E_INVALIDARG pStreamwasinvalid.

ISpStreamFormatConverter::GetBaseStreamISpStreamFormatConverter::GetBaseStreamgetsthebaseaudiostreamthatisbeingwrapped.HRESULTGetBaseStream(ISpStreamFormat**ppStream);

Parameters

ppStream[out]ThisparametercanbeNULLtosimplytestifthereisanassociatedbasestream.

Returnvalues


successfully.S_FALSE Nobasestreamispresent.E_POINTER Pointerisbadorinvalid.

ISpStreamFormatConverter::SetFormatISpStreamFormatConverter::SetFormatsetstheoutputformatoftheconverter.TheISpStreamFormat::GetFormatmethodreturnstheformatoftheoutput(converted)stream.HRESULTSetFormat(REFGUIDrguidFormatIdOfConvertedStream,constWAVEFORMATEX*pWaveFormatExOfConvertedStream);

Parameters

rguidFormatIdOfConvertedStream[in]Addressofthedataformatidentifierassociatedwiththerequestedoutputstream.CanbeGUID_NULLorSPDFID_WaveFormatEx.

pWaveFormatExOfConvertedStream[in]AddressoftheWAVEFORMATEXstructurecontainingthewavefileformatinformationoftheconvertedstream.MustbeNULLwithGUID_NULL.MustbeavalidWAVEFORMATEXwithSPDFID_WaveFormatEx.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_INVALIDARG Oneofthefollowingwas

encountered:rguidFormatIdOfConvertedStreamisneitherGUID_NULLorSPDFID_WaveFormatEx;

pWaveFormatExOfConvertedStreamisnotvalidforthesuppliedREFGUID.

Remarks

ThehelperclassCSpStreamFormatandtheSPSTREAMFORMATenumerationcanbeusedtoavoidthepossibilityoftyposormistakeswhenfillingintheWAVEFORMATEXstructure.

ISpStreamFormatConverter::ResetSeekPositionISpStreamFormatConverter::ResetSeekPositionresetstheformatconverter'sstreamseekpositiontothestartofthestream.Thismethodchangestheseekpositionofthebasestreamtozero.HRESULTResetSeekPosition(void);

Parameters

None.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.SPERR_UNINITIALIZED Currentstreambaseis

uninitialized.

ISpStreamFormatConverter::ScaleConvertedToBaseOffsetISpStreamFormatConverter::ScaleConvertedToBaseOffsetmapsastreamoffsetfromtheconvertedstreamtotheequivalentoffsetinthebasestream.

HRESULTScaleConvertedToBaseOffset(ULONGLONGullOffsetConvertedStream,ULONGLONG*pullOffsetBaseStream);

Parameters

ullOffsetConvertedStreamTheoffsetoftheoutput(converted)stream.

pullOffsetBaseStreamTheequivalentoffsetinthebase(unconverted)stream.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_POINTER pullOffsetBaseStreamisinvalid.SPERR_UNINITIALIZED Thebasestreamhasnotbeen

initialized.

RemarksWhenperformingamappingwithacompressedformat,itispossibletointroducesmallroundingerrors,sincethecontentoftheaudioisnotusedtoperformtheconversion.

ISpStreamFormatConverter::ScaleBaseToConvertedOffsetISpStreamFormatConverter::ScaleBaseToConvertedOffsetconvertsanoffsetinthebasestreamintotheequivalentoffsetintheconvertedstream.Thismethodisprimarilyusedinternallytomapeventoffsets.HRESULTScaleBaseToConvertedOffset(ULONGLONGullOffsetBaseStream,ULONGLONG*pullOffsetConvertedStream);

Parameters

ullOffsetBaseStreamThecurrentoffsetinthebase(unconverted)stream.

pullOffsetConvertedStreamThenewoffsetintheoutput(converted)stream.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.E_POINTER pullOffsetConvertedStreamisbador

invalid.SPERR_UNINITIALIZED Thebasestreamisnotinitialized.E_INVALIDARG ullOffsetBaseStreamislessthanthe

initialseekpositionofthecurrentsteam.*pullOffsetConvertedStreamissetto0xFFFFFFFFFFFFFFFF.

RemarksWhenperformingamappingwithacompressedformat,itispossibletointroducesmallroundingerrors,sincethecontentoftheaudioisnotusedtoperformtheconversion.

ISpTranscriptAtranscriptisatextstringassociatedwithapieceofaudiodata.TheSAPISpStreamobjectsupportstheISpTranscriptinterfaceforwavaudiofiles.

AssociatedClassIDsThefollowingclassIDs(CLSID)maybeusedwiththisinterface.AcompleteCLSIDlistingforallinterfacesisintheClassIDssection.

CLSID_SpStream


ISpTranscriptMethods DescriptionGetTranscript Getsthecurrenttranscript.AppendTranscript Addsthecurrenttexttothe

transcript.

DevelopmentHelpers

HelperEnumerations,FunctionsandClasses DescriptionCSpDynamicString Classformanagingdynamically

sizedUnicodestrings

ISpTranscript::GetTranscriptISpTranscript::GetTranscriptgetsthecurrenttranscript.ThestringreturnedwillbeallocatedbyCoTaskMemAllocandapplicationsimplementingthismethodmustcallCoTaskMemFree()tofreememoryassociatedwiththisstring.HRESULTGetTranscript(WCHAR**ppszTranscript);

Parameters

ppszTranscript[out,string]Apointertothenull-terminatedtranscriptionstring.

Returnvalues

Value DescriptionS_OK Functioncompletedsuccessfully.

ppszTranscriptcontainsaCoTaskMemAllocatedstring.

E_OUTOFMEMORY Exceededavailablememory.SPERR_UNINITIALIZED Objecthasnotbeeninitialized.E_POINTER ppszTranscriptisbadorinvalid.S_FALSE Notranscriptispresentand

ppszTranscriptwillbeNULL.FAILED(hr) Appropriateerrormessage.

ExampleThefollowingcodesnippetillustratestheuseofISpTranscript::GetTranscript.HRESULThr=S_OK;

//Bindastreamtoanexistingwavefilehr=SPBindToFile(FILENAME,SPFM_READ_ONLY,&cpStream);//Checkhrhr=cpStream.QueryInterface(&cpTranscript);//CheckhrPWCHARpwszTranscript;hr=cpTranscript->GetTranscript(&pwszTranscript);//Checkhr

ISpTranscript::AppendTranscriptISpTranscript::AppendTranscriptaddsthecurrenttexttothetranscript.HRESULTAppendTranscript(constWCHAR*pszTranscript);

Parameters

pszTranscript[in,string]Thetextofthetranscript.IfpszTranscriptisNULL,thecurrenttranscriptisdeleted.Otherwise,thetextisappendedtothecurrenttranscript.

Returnvalues


successfully.E_INVALIDARG pszTranscriptisbadorinvalid.E_OUTOFMEMORY Exceededavailablememory.FAILED(hr) Appropriateerrormessage.

ExampleThefollowingcodesnippetillustratestheuseofISpTranscript::AppendTranscript.HRESULThr=S_OK;

//Bindastreamtoanexistingwavefilehr=SPBindToFile(FILENAME,SPFM_CREATE_ALWAYS,&cpStream);//Checkhrhr=cpStream.QueryInterface(&cpTranscript);//Checkhrhr=cpTranscript->AppendTranscript(L"thisisatest");//Checkhr

EventinginterfacesThissectionprovidesSAPI5eventinformation.

ISpNotifySourceISpNotifySink

ISpNotifyTranslatorISpEventSinkISpEventSource

ISpNotifyCallback

ISpNotifySourceInbothspeechsynthesisandspeechrecognition,applicationsreceivenotificationswhenwordshavebeenspokenorwhenphraseshavebeenrecognized.SAPIcomponentsthatgeneratenotificationsimplementanISpNotifySource.TheISpNotifySourceandISpNotifySinkinterfacesaloneonlyprovideamechanismforanotificationbutnoinformationontheeventsthatcausedthenotification.WithanISpEventSourceobject,anapplicationcanretrieveinformationabouttheeventsthatcausedthenotification.Applicationswillnottypicallyusethefree-threadedISpNotifySinkmechanismforreceivingSAPIeventnotifications.Theywilluseoneofthesimplifiedmethodsofeitherawindowmessage,callbackorWin32event.Notethatbothvariationsofcallbacksaswellasthewindowmessagenotificationrequireawindowmessagepumptorunonthethreadthatinitializedthenotificationsource.Callbackwillonlybecalledastheresultofwindowmessageprocessing,andwillalwaysbecalledonthesamethreadthatinitializedthenotifysource.However,usingWin32eventsforSAPIeventnotificationdoesnotrequireawindowmessagepump.

ImplementedBySpRecoContextSpSharedRecoContextSpVoiceSpMMAudioIn

SpMMAudioOutSpRecPlayAudioSpStreamFormatConverter


ISpNotifySourceMethods DescriptionSetNotifySink Setsuptheinstancetomake

free-threadedcallsthroughISpNotifySink::Notify.Thismethodcanalsobeusedtounregisteranexistingnotification.

SetNotifyWindowMessage Setsawindowhandletoreceivenotificationsaswindowmessages.

SetNotifyCallbackFunction Setsacallbackfunctiontoreceivenotifications.

SetNotifyCallbackInterface SetsanobjectderivedfromISpTasktoreceivenotifications.

SetNotifyWin32Event SetsupaWin32eventobjecttobeusedbythisinstancefornotifications.

WaitForNotifyEvent Ablockingcallwhichwaitsforanotification.

GetNotifyEventHandle RetrievesWin32eventhandleassociatedwiththisnotifysource.

ISpNotifySource::SetNotifySinkISpNotifySource::SetNotifySinksetsuptheinstancetomakefree-threadednotificationcallsthroughISpNotifySink::Notify.HRESULTSetNotifySink(ISpNotifySink*pNotifySink);

Parameters

pNotifySink[in]Pointertothenotificationinterface.IfpNotifySinkisNULL,anycurrentnotificationmechanism(notifysink,windowmessage,callback,orWin32event)isremoved.

Returnvalues


successfully.E_INVALIDARG Interfacepointerisinvalid.FAILED(hr) Appropriateerrormessage.

RemarksIfpNotifySinkisNULL,anynotificationmechanismcurrentlyassociatedwiththisnotifysourceisremoved.Becausefree-threadednotificationscanoccuronanythread,atanypointduringexecution,theyareextremelypronetodeadlocksandre-entranceproblems.SeethedocumentationforISpNotifySinkformoredetails.Mostapplicationswillfindoneoftheothernotificationmechanismsmucheasiertouse.


http://go.microsoft.com/fwlink?linkid=288&clcid=

Documents

Microsoft Speech SDK (SAPI 5.0) · SDK 5.1 menu. The binary and source files, projects, are available in the Samples folder of the Microsoft Speech SDK 5.1 folder. A description of