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]
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
http://go.microsoft.com/fwlink?linkid=230&clcid=0x409
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
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
AbouttheSDKTheMicrosoftSpeechSDKisdesignedtoworkwiththeindustry-leadingSpeechApplicationProgrammingInterface(SAPI)andMicrosoftcontinuousspeechrecognitionengineandMicrosoftconcatenatedspeechsynthesisengine(ortext-to-speech).MicrosoftSDKincludestools,samples,anddocumentationforbuildingspeechapplications.
MicrosoftVisualBasicSupportAsetofCOM-supportedspeechAutomationinterfacesisincludedinthisreleaseofMicrosoftSpeechSDK.ThatmeanslanguagesotherthanC/C++maynowuseSAPIforapplicationdevelopment.ThelanguagesthemselvesneedtosupportOLEautomation.CommonlanguageswhichmaybeusedincludesVisualBasic,C#,andJScript.SeeAutomationInterfacesandObjectsforadditionalinformation.
Thissectionincludesthefollowingtopics:LegalInformationRedistributableCodeRights
WhoShouldUseThisSDKHowtoReadNewsgroups
DeveloperSupportPlatformSDKRequirements
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
http://go.microsoft.com/fwlink?linkid=296&clcid=0x409
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
KnownIssuesInformationonknownissuesinSAPI5canbefoundintheKnowledgeBasearticlesintheMicrosoftSpeech.NETTechnologiessupporthomepage.
http://go.microsoft.com/fwlink/?LinkId=2891mailto:[email protected]://go.microsoft.com/fwlink?linkid=288&clcid=0x409
MicrosoftSpeechSDKSAPI5.1
http://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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
SAPI5IntroductionThissectionprovidesaSAPI5introduction.Thefollowingtopicisavailable:
SAPI5Overview
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
Application-LevelInterfacesThissectiondescribestheinterfacesandmethodsforincorporatingspeechintoapplications.TheyareintendedforuseattheAPIorapplicationlevel.SomemanagersorinterfacesmayhaveentriesalsoinEngine-LevelInterfacessection.However,entrieslistedhereapplyonlytotheapplicationlevel.
AudiointerfacesEventinginterfaces
GrammarCompilerinterfacesLexiconinterfaces
ResourceinterfacesSpeechRecognitioninterfaces
Text-to-Speechinterfaces
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpAudio::SetFormatISpAudio::SetFormatsetstheformatoftheaudiodevice.HRESULTSetFormat(REFGUIDrguidFmtId,constWAVEFORMATEX*pWaveFormatEx);
Parameters
rguidFmtId[in]TheREFGUIDfortheformattoset.TypicallythiswillbeSPDFID_WaveFormatEx.ThisisrequiredfortheSAPImultimediaobjects.
pWaveFormatEx[in]AddressoftheWAVEFORMATEXstructurecontainingthewavefileformatinformation.
Returnvalues
Value DescriptionS_OK Functioncompleted
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpAudio::GetStatusISpAudio::GetStatuspassesbackthestatusoftheaudiodevice.Thismethoddetermineswhetherthedeviceisrunning,stopped,closed,orpaused.Italsodeterminesthesizeofanybuffereddata.HRESULTGetStatus(SPAUDIOSTATUS*pStatus);
Parameters
pStatus[out]PointertoanSPAUDIOSTATUSbuffertobefilledwiththestatusdetails.
Returnvalues
Value DescriptionS_OK Functioncompleted
successfully.E_POINTER pStatusisinvalid.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpAudio::GetBufferInfoISpAudio::GetBufferInfopassesbacktheaudiostreambufferinformation.HRESULTGetBufferInfo(SPAUDIOBUFFERINFO*pBuffInfo);
Parameters
pBuffInfo[out]PointertotheSPAUDIOBUFFERINFObuffer.
Returnvalues
Value DescriptionS_OK Functioncompleted
successfully.E_POINTER pBuffInfoisinvalid.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpAudio::EventHandleISpAudio::EventHandlereturnsaWin32eventhandlethatapplicationscanusetowaitforstatuschangesintheI/Ostream.HANDLEEventHandle(void);
ParametersNone
Returnvalues
Value DescriptionHANDLE Returnsvalidevent
handle.
RemarksThehandlemayuseoneofthevariousWin32waitfunctions,suchasWaitForSingleObjectorWaitForMultipleObjects.Forreadstreams,settheeventwhenthereisdataavailabletoreadandresetitwheneverthereisnoavailabledata.Forwritestreams,settheeventwhenallofthedatahasbeenwrittentothedevice,andresetitatanytimewhenthereisstilldataavailabletobeplayed.Thecallershouldnotclosethereturnedhandle,norshouldthecallereverusetheeventhandleaftercallingRelease()ontheaudioobject.Theaudiodevicewillclosethehandleonthefinalreleaseoftheobject.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpAudio::GetVolumeLevelISpAudio::GetVolumeLevelpassesbackthecurrentvolumelevel.Thevolumelevelisonalinearscalefromzeroto10000.HRESULTGetVolumeLevel(ULONG*pLevel);
Parameters
pLevel[out]Pointertothereturnedvolumelevel.
Returnvalues
Value DescriptionS_OK Functioncompleted
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpAudio::SetVolumeLevelISpAudio::SetVolumeLevelsetsthecurrentvolumelevel.Itisonalinearscalefromzeroto10000.HRESULTSetVolumeLevel(ULONGLevel);
Parameters
Level[in]Thenewvolumelevel.
Returnvalues
Value DescriptionS_OK Functioncompleted
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpAudio::GetBufferNotifySizeISpAudio::GetBufferNotifySizeretrievestheaudiostreambuffersizeinformation.ThisinformationisusedtodeterminewhentheeventreturnedbyISpAudio::EventHandleissetorreset.HRESULTGetBufferNotifySize(ULONG*pcbSize);
Parameters
pcbSize[out]Addressofthesizeinformation,specifiedinbytes,thatisassociatedwiththeaudiostreambuffer.
Returnvalues
Value DescriptionS_OK Functioncompleted
successfully.E_POINTER Invalidpointer.
RemarksForreadstreams,theeventissetiftheaudiobufferedisgreaterthanorequaltothevaluesetinpcbSize,otherwisetheeventinformationisreset.Forwritestreams,theeventissetiftheaudiobufferedislessthanthevaluesetinpcbSize,otherwisetheeventinformationisreset.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpAudio::SetBufferNotifySizeISpAudio::SetBufferNotifySizesetstheaudiostreambuffersizeinformation.ThisinformationisusedtodeterminewhentheeventreturnedbyISpAudio::EventHandleissetorreset.HRESULTSetBufferNotifySize(ULONGcbSize);
Parameters
cbSize[in]Thesize,specifiedinbytes,oftheinformationassociatedwiththeaudiostreambuffer.
Returnvalues
Value DescriptionS_OK Functioncompleted
successfully.FAILED(hr) Appropriateerrormessage.
RemarksForreadstreams,theeventissetiftheaudiobufferedisgreaterthanorequaltothevaluesetincbSize,otherwisetheeventinformationisreset.Forwritestreams,theeventissetiftheaudiobufferedislessthanthevaluesetincbSize,otherwisetheeventinformationisreset.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
MethodsinVtableOrder
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
Value DescriptionS_OK Functioncompleted
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.
FAILED(hr) Appropriateerrormessage.
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
FAILED(hr) Appropriateerrormessage.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpMMSysAudio::GetDeviceIdISpMMSysAudio::GetDeviceIdpassesbackthemultimediadeviceIDbeingusedbytheaudioobject.HRESULTGetDeviceId(UINT*puDeviceId);
Parameters
puDeviceId[out]PointerreceivingthedeviceID.
Returnvalues
Value DescriptionS_OK Functioncompleted
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
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpStreamThisinterfaceprovidestwodistinctfunctions:
TheapplicationdevelopercanwrapanexistingstreamupbyprovidingbothanIStreamanditsformatsothattheunderlyingISpStreamFormatcanprovidethisdatatoSAPIwhenrequired.ThenewISpStreamobjectcanbeusedasaninputforSAPIwhereverSAPIrequiresanISpStreamFormat.ISpStreamcreatesanobjectfromafilesuitableforSAPIusageusingBindToFile.ThehelperfunctionSPBindToFilemayalsobeusedtosimplifythisprocessevenfurther.
ImplementedBySpStream
MethodsinVtableOrder
ISpStreamMethods DescriptionSetBaseStream Setsthebaseaddressoftheaudio
stream.GetBaseStream Retrievesthebaseaddressofthe
audiostream.BindToFile Bindstheaudiostreamtothefile
thatitidentifies.Close Closestheaudiostream.
DevelopmentHelpers
HelperEnumerations,FunctionsandClasses DescriptionSPSTREAMFORMAT SAPIsupportedstreamformatsCSpStreamFormat ClassformanagingSAPIsupported
streamformatsandWAVEFORMATEXstructures
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
FAILED(hr) Appropriateerrormessage.
Remarks
ThehelperclassCSpStreamFormatandtheSPSTREAMFORMATenumerationcanbeusedtoavoidthepossibilityoftyposormistakeswhenfillingintheWAVEFORMATEXstructure.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpStream::CloseISpStream::Closeclosestheaudiostreamandvalidatesthecloseoperation.HRESULTClose(void);
ParametersNone.
Returnvalues
Value DescriptionS_OK Functioncompletedsuccessfully.SPERR_STREAM_CLOSED Thestreamisclosedorunavailable.FAILED(hr) Appropriateerrormessage.
RemarksReleasingtheISpStreamobjectwillautomaticallycallthismethod.However,anyerrorsencounteredwillnotbesentasnotificationstotheapplication.Hencetheapplicationcanexplicitlycallthismethodfirsttocheckthatnoerrorsoccurredduringthecloseoperation.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpStreamFormatISpStreamFormatinheritsfromIStream.ThisistheminimumextrainterfacerequiredbySAPIinadditiontotheIStreaminterface.Usingthisinterface,SAPIcanquerythestreamtodeterminetheformatofthestreamdata.AlmostallSAPIfunctionsrequiringorreturningastreamwillrequireorreturnanISpStreamFormat.
WhentoImplementThisinterfaceshouldbeimplementedwhenimplementingastreamfromscratch.IfanIStreamalreadyexists,SAPIcanuseitwiththeprovidedISpStreamobject.Innormalusage,thisinterfacedoesnotneedtobeimplemented.
ImplementedBySpMMAudioIn
SpMMAudioOutSpStreamFormatConverter
SpStream
MethodsinVtableOrder
ISpStreamFormatMethods DescriptionGetFormat Passesbackthecachedformatof
thestream.
DevelopmentHelpers
HelperEnumerations,FunctionsandClasses Description
SPSTREAMFORMAT SAPIsupportedstreamformatsCSpStreamFormat ClassformanagingSAPIsupported
streamformatsandWAVEFORMATEXstructures
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MethodsinVtableOrder
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
streamformatsandWAVEFORMATEXstructures
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
Value DescriptionS_OK Functioncompleted
successfully.E_INVALIDARG pStreamwasinvalid.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpStreamFormatConverter::GetBaseStreamISpStreamFormatConverter::GetBaseStreamgetsthebaseaudiostreamthatisbeingwrapped.HRESULTGetBaseStream(ISpStreamFormat**ppStream);
Parameters
ppStream[out]ThisparametercanbeNULLtosimplytestifthereisanassociatedbasestream.
Returnvalues
Value DescriptionS_OK Functioncompleted
successfully.S_FALSE Nobasestreamispresent.E_POINTER Pointerisbadorinvalid.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpStreamFormatConverter::ResetSeekPositionISpStreamFormatConverter::ResetSeekPositionresetstheformatconverter'sstreamseekpositiontothestartofthestream.Thismethodchangestheseekpositionofthebasestreamtozero.HRESULTResetSeekPosition(void);
Parameters
None.
Returnvalues
Value DescriptionS_OK Functioncompletedsuccessfully.SPERR_UNINITIALIZED Currentstreambaseis
uninitialized.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpTranscriptAtranscriptisatextstringassociatedwithapieceofaudiodata.TheSAPISpStreamobjectsupportstheISpTranscriptinterfaceforwavaudiofiles.
AssociatedClassIDsThefollowingclassIDs(CLSID)maybeusedwiththisinterface.AcompleteCLSIDlistingforallinterfacesisintheClassIDssection.
CLSID_SpStream
MethodsinVtableOrder
ISpTranscriptMethods DescriptionGetTranscript Getsthecurrenttranscript.AppendTranscript Addsthecurrenttexttothe
transcript.
DevelopmentHelpers
HelperEnumerations,FunctionsandClasses DescriptionCSpDynamicString Classformanagingdynamically
sizedUnicodestrings
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
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
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpTranscript::AppendTranscriptISpTranscript::AppendTranscriptaddsthecurrenttexttothetranscript.HRESULTAppendTranscript(constWCHAR*pszTranscript);
Parameters
pszTranscript[in,string]Thetextofthetranscript.IfpszTranscriptisNULL,thecurrenttranscriptisdeleted.Otherwise,thetextisappendedtothecurrenttranscript.
Returnvalues
Value DescriptionS_OK Functioncompleted
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
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
EventinginterfacesThissectionprovidesSAPI5eventinformation.
ISpNotifySourceISpNotifySink
ISpNotifyTranslatorISpEventSinkISpEventSource
ISpNotifyCallback
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpNotifySourceInbothspeechsynthesisandspeechrecognition,applicationsreceivenotificationswhenwordshavebeenspokenorwhenphraseshavebeenrecognized.SAPIcomponentsthatgeneratenotificationsimplementanISpNotifySource.TheISpNotifySourceandISpNotifySinkinterfacesaloneonlyprovideamechanismforanotificationbutnoinformationontheeventsthatcausedthenotification.WithanISpEventSourceobject,anapplicationcanretrieveinformationabouttheeventsthatcausedthenotification.Applicationswillnottypicallyusethefree-threadedISpNotifySinkmechanismforreceivingSAPIeventnotifications.Theywilluseoneofthesimplifiedmethodsofeitherawindowmessage,callbackorWin32event.Notethatbothvariationsofcallbacksaswellasthewindowmessagenotificationrequireawindowmessagepumptorunonthethreadthatinitializedthenotificationsource.Callbackwillonlybecalledastheresultofwindowmessageprocessing,andwillalwaysbecalledonthesamethreadthatinitializedthenotifysource.However,usingWin32eventsforSAPIeventnotificationdoesnotrequireawindowmessagepump.
ImplementedBySpRecoContextSpSharedRecoContextSpVoiceSpMMAudioIn
SpMMAudioOutSpRecPlayAudioSpStreamFormatConverter
MethodsinVtableOrder
ISpNotifySourceMethods DescriptionSetNotifySink Setsuptheinstancetomake
free-threadedcallsthroughISpNotifySink::Notify.Thismethodcanalsobeusedtounregisteranexistingnotification.
SetNotifyWindowMessage Setsawindowhandletoreceivenotificationsaswindowmessages.
SetNotifyCallbackFunction Setsacallbackfunctiontoreceivenotifications.
SetNotifyCallbackInterface SetsanobjectderivedfromISpTasktoreceivenotifications.
SetNotifyWin32Event SetsupaWin32eventobjecttobeusedbythisinstancefornotifications.
WaitForNotifyEvent Ablockingcallwhichwaitsforanotification.
GetNotifyEventHandle RetrievesWin32eventhandleassociatedwiththisnotifysource.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=0x409
ISpNotifySource::SetNotifySinkISpNotifySource::SetNotifySinksetsuptheinstancetomakefree-threadednotificationcallsthroughISpNotifySink::Notify.HRESULTSetNotifySink(ISpNotifySink*pNotifySink);
Parameters
pNotifySink[in]Pointertothenotificationinterface.IfpNotifySinkisNULL,anycurrentnotificationmechanism(notifysink,windowmessage,callback,orWin32event)isremoved.
Returnvalues
Value DescriptionS_OK Functioncompleted
successfully.E_INVALIDARG Interfacepointerisinvalid.FAILED(hr) Appropriateerrormessage.
RemarksIfpNotifySinkisNULL,anynotificationmechanismcurrentlyassociatedwiththisnotifysourceisremoved.Becausefree-threadednotificationscanoccuronanythread,atanypointduringexecution,theyareextremelypronetodeadlocksandre-entranceproblems.SeethedocumentationforISpNotifySinkformoredetails.Mostapplicationswillfindoneoftheothernotificationmechanismsmucheasiertouse.
MicrosoftSpeechSDKSAPI5.1
http://go.microsoft.com/fwlink?linkid=288&clcid=