CAWT 2.6.0 Reference Manual

# ::SapiTop, Main

The `Sapi` namespace provides commands to control the Microsoft Speech API (SAPI).

Microsoft SAPI documentation

## CommandsSapi, Top, Main

#### GetEnum [::Sapi]Sapi, Top, Main

Get numeric value of an enumeration.

GetEnum enumOrString

`enumOrString` | Enumeration name

Returns the numeric value of an enumeration.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnumNames

Show source

    proc ::Sapi::GetEnum {enumOrString} {

        # Get numeric value of an enumeration.
        #
        # enumOrString - Enumeration name
        #
        # Returns the numeric value of an enumeration.
        #
        # See also: GetEnumName GetEnumTypes GetEnumVal GetEnumNames

        set retVal [catch { expr int($enumOrString) } enumInt]
        if { $retVal == 0 } {
            return $enumInt
        } else {
            return [GetEnumVal $enumOrString]
        }
    }

#### GetEnumName [::Sapi]Sapi, Top, Main

Get name of a given enumeration type and numeric value.

GetEnumName enumType enumVal

`enumType` | Enumeration type
`enumVal` | Enumeration numeric value.

Returns the list of names of a given enumeration type.

See also: GetEnumNames, GetEnumTypes, GetEnumVal, GetEnum

Show source

    proc ::Sapi::GetEnumName {enumType enumVal} {

        # Get name of a given enumeration type and numeric value.
        #
        # enumType - Enumeration type
        # enumVal  - Enumeration numeric value.
        #
        # Returns the list of names of a given enumeration type.
        #
        # See also: GetEnumNames GetEnumTypes GetEnumVal GetEnum

        variable enums

        set enumName ""
        if { [info exists enums($enumType)] } {
            foreach { key val } $enums($enumType) {
                if { $val eq $enumVal } {
                    set enumName $key
                    break
                }
            }
        }
        return $enumName
    }

#### GetEnumNames [::Sapi]Sapi, Top, Main

Get names of a given enumeration type.

GetEnumNames enumType

`enumType` | Enumeration type

Returns the list of names of a given enumeration type.

See also: GetEnumName, GetEnumTypes, GetEnumVal, GetEnum

Show source

    proc ::Sapi::GetEnumNames {enumType} {

        # Get names of a given enumeration type.
        #
        # enumType - Enumeration type
        #
        # Returns the list of names of a given enumeration type.
        #
        # See also: GetEnumName GetEnumTypes GetEnumVal GetEnum

        variable enums

        if { [info exists enums($enumType)] } {
            foreach { key val } $enums($enumType) {
                lappend nameList $key
            }
            return $nameList
        } else {
            return [list]
        }
    }

#### GetEnumTypes [::Sapi]Sapi, Top, Main

Get available enumeration types.

GetEnumTypes

Returns the list of available enumeration types.

See also: GetEnumName, GetEnumNames, GetEnumVal, GetEnum

Show source

    proc ::Sapi::GetEnumTypes {} {

        # Get available enumeration types.
        #
        # Returns the list of available enumeration types.
        #
        # See also: GetEnumName GetEnumNames GetEnumVal GetEnum

        variable enums

        return [lsort -dictionary [array names enums]]
    }

#### GetEnumVal [::Sapi]Sapi, Top, Main

Get numeric value of an enumeration name.

GetEnumVal enumName

`enumName` | Enumeration name

Returns the numeric value of an enumeration name.

See also: GetEnumName, GetEnumTypes, GetEnumNames, GetEnum

Show source

    proc ::Sapi::GetEnumVal {enumName} {

        # Get numeric value of an enumeration name.
        #
        # enumName - Enumeration name
        #
        # Returns the numeric value of an enumeration name.
        #
        # See also: GetEnumName GetEnumTypes GetEnumNames GetEnum

        variable enums

        foreach enumType [GetEnumTypes] {
            set ind [lsearch -exact $enums($enumType) $enumName]
            if { $ind >= 0 } {
                return [lindex $enums($enumType) [expr { $ind + 1 }]]
            }
        }
        return ""
    }

#### GetSpeakOptions [::Sapi]Sapi, Top, Main

Get speak options.

GetSpeakOptions appId ?args?

`appId` | Identifier of the SAPI instance.
`args` | Options described below.
`-rate` | Get the speaking rate of the voice. Values range from -10 (slowest) to 10 (fastest).
`-volume` | Set the volume (loudiness) of the voice. Values range from 0 to 100.

Example:

    lassign [GetSpeakOptions $appId -rate -volume] rate volume

Returns the specified options as a list.

See also: Open, Speak, SetSpeakOptions

Show source

    proc ::Sapi::GetSpeakOptions {appId args} {

        # Get speak options.
        #
        # appId - Identifier of the SAPI instance.
        # args  - Options described below.
        #
        # -rate   - Get the speaking rate of the voice.
        #           Values range from -10 (slowest) to 10 (fastest).
        # -volume - Set the volume (loudiness) of the voice.
        #           Values range from 0 to 100.
        #
        # Example:
        #     lassign [GetSpeakOptions $appId -rate -volume] rate volume
        #
        # Returns the specified options as a list.
        #
        # See also: Open Speak SetSpeakOptions

        set valList [list]
        foreach key $args {
            switch -exact -nocase -- $key {
                "-rate"   { lappend valList [$appId Rate] }
                "-volume" { lappend valList [$appId Volume] }
                default   { error "GetSpeakOptions: Unknown key \"$key\" specified" }
            }
        }
        return $valList
    }

#### GetVoiceByName [::Sapi]Sapi, Top, Main

Get a voice identifier by specifying its name.

GetVoiceByName appId voiceName

`appId` | Identifier of the SAPI instance.
`voiceName` | Name of the voice.

Returns the voice identifier.

See also: Open, Speak, GetVoiceNames, SetVoice

Show source

    proc ::Sapi::GetVoiceByName {appId voiceName} {

        # Get a voice identifier by specifying its name.
        #
        # appId     - Identifier of the SAPI instance.
        # voiceName - Name of the voice.
        #
        # Returns the voice identifier.
        #
        # See also: Open Speak GetVoiceNames SetVoice

        set voices [$appId GetVoices]
        set numVoices [$voices Count]
        for { set v 0 } { $v < $numVoices } { incr v } {
            set voice [$voices Item $v]
            if { [$voice GetDescription] eq $voiceName } {
                Cawt Destroy $voices
                return $voice
            }
            Cawt Destroy $voice
        }
        error "Voice \"$voiceName\" not available."
    }

#### GetVoiceNames [::Sapi]Sapi, Top, Main

Get a list of voice names.

GetVoiceNames appId

`appId` | Identifier of the SAPI instance.

Returns the list of voice names.

See also: Open, Speak, GetVoiceByName, SetVoice

Show source

    proc ::Sapi::GetVoiceNames {appId} {

        # Get a list of voice names.
        #
        # appId - Identifier of the SAPI instance.
        #
        # Returns the list of voice names.
        #
        # See also: Open Speak GetVoiceByName SetVoice

        set voicesList [list]
        set voices [$appId GetVoices]
        set numVoices [$voices Count]
        for { set v 0 } { $v < $numVoices } { incr v } {
            set voice [$voices Item $v]
            lappend voicesList [$voice GetDescription]
            Cawt Destroy $voice
        }
        Cawt Destroy $voices
        return $voicesList
    }

#### Open [::Sapi]Sapi, Top, Main

Open a SAPI object instance.

Open

Returns the SAPI object identifier.

See also: Speak, SetSpeakOptions, GetVoiceNames

Show source

    proc ::Sapi::Open {} {

                # Open a SAPI object instance.
                #
                # Returns the SAPI object identifier.
                #
                # See also: Speak SetSpeakOptions GetVoiceNames

        	variable sapiAppName

                set appId [Cawt GetOrCreateApp $sapiAppName true]
                return $appId
    }

#### SetSpeakOptions [::Sapi]Sapi, Top, Main

Set speak options.

SetSpeakOptions appId ?args?

`appId` | Identifier of the SAPI instance.
`args` | Options described below.
`-rate <int>` | Set the speaking rate of the voice. Values range from -10 (slowest) to 10 (fastest).
`-volume <int>` | Set the volume (loudiness) of the voice. Values range from 0 to 100.

Returns no value.

See also: Open, Speak, GetSpeakOptions

Show source

    proc ::Sapi::SetSpeakOptions {appId args} {

        # Set speak options.
        #
        # appId - Identifier of the SAPI instance.
        # args  - Options described below.
        #
        # -rate <int>   - Set the speaking rate of the voice.
        #                 Values range from -10 (slowest) to 10 (fastest).
        # -volume <int> - Set the volume (loudiness) of the voice.
        #                 Values range from 0 to 100.
        #
        # Returns no value.
        #
        # See also: Open Speak GetSpeakOptions

        foreach { key value } $args {
            if { $value eq "" } {
                error "SetSpeakOptions: No value specified for key \"$key\""
            }
            switch -exact -nocase -- $key {
                "-rate"   { $appId Rate   [expr int( $value)] }
                "-volume" { $appId Volume [expr int( $value)] }
                default   { error "SetSpeakOptions: Unknown key \"$key\" specified" }
            }
        }
    }

#### SetVoice [::Sapi]Sapi, Top, Main

Set the voice for speaking.

SetVoice appId voiceId

`appId` | Identifier of the SAPI instance.
`voiceId` | Identifier of the voice.

Returns no value.

See also: Open, SetSpeakOptions, GetVoiceByName

Show source

    proc ::Sapi::SetVoice {appId voiceId} {

        # Set the voice for speaking.
        #
        # appId   - Identifier of the SAPI instance.
        # voiceId - Identifier of the voice.
        #
        # Returns no value.
        #
        # See also: Open SetSpeakOptions GetVoiceByName

        # Workaround from Ashok to directly invoke the Voice
        # property method as a propertyputref (type 8).
        $appId -invoke Voice [list 8] [list $voiceId]
    }

#### Speak [::Sapi]Sapi, Top, Main

Speak a sentence.

Speak appId str ?args?

`appId` | Identifier of the SAPI instance.
`str` | String to be spoken.
`args` | Options described below.
`-flags <int>` | Bitflag of enumerations of type Enum::SpeechVoiceSpeakFlags

Returns no value.

See also: Open, SetSpeakOptions, GetVoiceNames

Show source

    proc ::Sapi::Speak {appId str args} {

        # Speak a sentence.
        #
        # appId - Identifier of the SAPI instance.
        # str   - String to be spoken.
        # args  - Options described below.
        #
        # -flags <int> - Bitflag of enumerations of type [Enum::SpeechVoiceSpeakFlags]
        #
        # Returns no value.
        #
        # See also: Open SetSpeakOptions GetVoiceNames

        set flags $Sapi::SVSFDefault
        foreach { key value } $args {
            if { $value eq "" } {
                error "Speak: No value specified for key \"$key\""
            }
            switch -exact -nocase -- $key {
                "-flags" { set flags $value }
                default  { error "Speak: Unknown key \"$key\" specified" }
            }
        }
        $appId Speak $str [expr int($flags)]
    }

# Start page

# Cawt

# Office

# Excel

# Ppt

# Word

# Outlook

# OneNote

# Sapi

# Office::Enum

# Excel::Enum

# Ppt::Enum

# Word::Enum

# Outlook::Enum

# OneNote::Enum

# Sapi::Enum

# Earth

# Explorer

# Ocr

# Reader

# Matlab

# Sapi

## Commands

#### GetEnum Get numeric value of an enumeration.

#### GetEnumName Get name of a given enumeration type and numeric value.

#### GetEnumNames Get names of a given enumeration type.

#### GetEnumTypes Get available enumeration types.

#### GetEnumVal Get numeric value of an enumeration name.

#### GetSpeakOptions Get speak options.

#### GetVoiceByName Get a voice identifier by specifying its name.

#### GetVoiceNames Get a list of voice names.

#### Open Open a SAPI object instance.

#### SetSpeakOptions Set speak options.

#### SetVoice Set the voice for speaking.

#### Speak Speak a sentence.

Document generated by Ruff!