Sample storage client

TTSaaS offers a Python client application that you can download and run on Linux or Windows to upload and delete synthesis resources using the Storage API. To run this client, you need:

Download this zip file and extract its files into the same directory as the nuance directory, which contains your proto files and Python stubs.

On Linux, give run-storage-client.sh execute permission with chmod +x. For example:

unzip sample-storage-client.zip
chmod +x run-storage-client.sh
  Python storage client, storage-client.py  

These are the resulting client files, in the same directory as the nuance directory:

├── run-storage-client.bat
├── run-storage-client.sh
├── storage-client.py
└── nuance
    ├── rpc (RPC message files)
    └── tts
        ├── storage
        │   └── v1beta1
        │       ├── storage_pb2_grpc.py
        │       ├── storage_pb2.py
        │       └── storage.proto
        └── v1 (Synthesizer files)

You can use the storage client to upload or delete resources. Here are a few scenarios you can try.

Get help

For a quick check that the client is working, and to see the arguments it accepts, run it using the help (-h or --help) option.

See the results below and notice:

  • --server_url: The URL of the storage server. The sample script specifies the Mix service, tts.api.nuance.com on its default port, 443.

  • --token: An access token to authorize the application. See Edit run script next.

  • --upload or --delete: One of these options is required. Other options depend on the operation requested.

The results are the same on Linux and Windows:

python3 storage-client.py --help

usage: storage-client.py [-options]

options:
  -h, --help                         Show this help message and exit
  --server_url [SERVER_URL]          Server hostname (default=localhost)
  --token [TOKEN]                    Access token
  --max_chunk_size_bytes [num]       Max size (in bytes) of each file chunk, default=4096
  --upload                           Send an Upload RPC. Requires the --context_tag, --name and
                                     other resource-specific options.
  --delete                           Send a Delete RPC. Requires the --uri option.
  --file [file]                      File to upload. If an ActivePrompt Database, must be packaged
                                     as a zip.
  --context_tag [tag]                Context tag
  --name [name]                      Resource name
  --type [type]                      Resource type. Must be one of: [activeprompt, user_dictionary,
                                     text_ruleset, wav]
  --language [type]                  IETF language code. Required if type is [user_dictionary,
                                     text_ruleset])
  --voice [type]                     ActivePrompt voice
  --voice_model [type]               ActivePrompt voice model
  --voice_version [type]             ActivePrompt voice version
  --vocalizer_studio_version [type]  ActivePrompt Vocalizer Studio version
  --uri [uri]                        URI to delete

Edit run script

Edit the sample shell script or batch file to add your Mix client ID and secret. The script also changes the colons in the client ID to %3A so curl can parse the value correctly.

#!/bin/bash
       
CLIENT_ID=<Mix client ID, starting with appID:>
SECRET=<Mix client secret>
#Change colons (:) to %3A in client ID
CLIENT_ID=${CLIENT_ID//:/%3A}

MY_TOKEN="`curl -s -u "$CLIENT_ID:$SECRET" \
"https://auth.crt.nuance.com/oauth2/token" \
-d "grant_type=client_credentials" -d "scope=asr nlu tts" \
| python -c 'import sys, json; print(json.load(sys.stdin)["access_token"])'`"

python3 storage-client.py --server_url tts.api.nuance.com --token $MY_TOKEN \
...
@echo off
setlocal enabledelayedexpansion

set CLIENT_ID=<Mix client ID, starting with appID:>
set SECRET=<Mix client secret>
rem Change colons (:) to %3A in client ID
set CLIENT_ID=!CLIENT_ID::=%%3A!

set command=curl -s ^
-u %CLIENT_ID%:%SECRET% ^
-d "grant_type=client_credentials" -d "scope=tts" ^
https://auth.crt.nuance.com/oauth2/token

for /f "delims={}" %%a in ('%command%') do (
  for /f "tokens=1 delims=:, " %%b in ("%%a") do set key=%%b
  for /f "tokens=2 delims=:, " %%b in ("%%a") do set value=%%b
  goto done:
)

:done

rem Remove quotes
set MY_TOKEN=!value:"=!

python storage-client.py --server_url tts.api.nuance.com --token %MY_TOKEN% ^
...

Then use the shell script to add the options required for the type of resource you want to upload. See the following scenarios for details.

Upload user dictionary

Follow these steps to upload a user dictionary created in Nuance Vocalizer Studio. See User dictionary.

  1. Open the shell script or batch file and edit the arguments for uploading a user dictionary, for example:

    ...
    python3 storage-client.py --server_url tts.api.nuance.com --token $MY_TOKEN \
    --upload --type user_dictionary --file resources/user-dictionary-1.dcb \
    --context_tag coffee_app --name coffee_dict \
    --language en-us 
    ...
    python storage-client.py --server_url tts.api.nuance.com --token %MY_TOKEN% ^
    --upload --type user_dictionary --file ..\resources\user-dictionary-1.dcb ^
    --context_tag coffee_app --name coffee_dict ^
    --language en-us 
  2. Run the client using the shell script or batch file to upload the user dictionary.

    ./run-storage-client.sh
    run-storage-client.bat

The client uploads the dictionary to central Mix storage.

2023-06-22 17:59:41,388 INFO  Type is User Dictionary
2023-06-22 17:59:41,561 INFO  Done reading data
2023-06-22 17:59:41,677 INFO  status {
  status_code: OK
}
uri: "urn:nuance-mix:tag:tuning:lang/coffee_app/coffee_dict/en-us/mix.tts?type=userdict"

To use this dictionary in your synthesis requests, reference it using the URN returned. See Run client with resources. The type=userdict field is for information only and is not required as part of the reference.

Upload ActivePrompts

Follow these steps to upload an ActivePrompt database created in Nuance Vocalizer Studio. Vocalizer Studio, a separate product, is a graphical TTS tuning environment. See ActivePrompt database.

  1. Open the shell script or batch file and edit the arguments for uploading an ActivePrompt database, for example:

    ...
    python3 storage-client.py --server_url tts.api.nuance.com --token $MY_TOKEN \
    --upload --type activeprompt --file resources/activeprompts.zip \
    --context_tag coffee_app --name coffee_prompts \
    --voice evan --voice_model enhanced --voice_version 1.0.0 \
    --vocalizer_studio_version 3.4  
    ...
    python storage-client.py --server_url tts.api.nuance.com --token %MY_TOKEN% ^
    --upload --type activeprompt --file ..\resources\activeprompts.zip ^
    --context_tag coffee_app --name coffee_prompts ^
    --voice evan --voice_model enhanced --voice_version 1.0.0 ^
    --vocalizer_studio_version 3.4 
  2. Run the client using the shell script or batch file to upload the ActivePrompt database.

    ./run-storage-client.sh
    run-storage-client.bat

The client uploads the database to Mix storage. To use this ActivePrompt database in your synthesis requests, reference it using the URN returned. The type=activeprompt field is for information only and is not required as part of the reference.

2023-06-22 18:05:17,294 INFO  Type is ActivePromptDB
2023-06-22 18:05:17,522 INFO  Done reading data
2023-06-22 18:05:17,637 INFO  status {
  status_code: OK
}
uri: "urn:nuance-mix:tag:tuning:voice/coffee_app/coffee_prompts/evan/mix.tts?type=activeprompt"

Upload ruleset

Follow these steps to upload a text ruleset. Binary (or encrypted) rulesets are not supported. See Ruleset.

  1. Open the shell script or batch file and edit the arguments for uploading a text ruleset, for example:

    ...
    python3 storage-client.py --server_url tts.api.nuance.com --token $MY_TOKEN \
    --upload --type text_ruleset --file resources/ruleset-1.rst.txt \
    --context_tag coffee_app --name coffee_rules \
    --language en-us
    ...
    python storage-client.py --server_url tts.api.nuance.com --token %MY_TOKEN% ^
    --upload --type text_ruleset --file ..\resources\ruleset-1.rst.txt ^
    --context_tag coffee_app --name coffee_rules ^
    --language en-us 
  2. Run the client using the shell script or batch file to upload the ruleset.

    ./run-storage-client.sh
    run-storage-client.bat

The client uploads the ruleset to Mix storage. To use this ruleset in your synthesis requests, reference it using the URN returned. The type=textruleset field is for information only and is not required as part of the reference.

2023-06-22 18:06:40,491 INFO  Type is Text User Ruleset
2023-06-22 18:06:40,633 INFO  Done reading data
2023-06-22 18:06:40,778 INFO  status {
  status_code: OK
}
uri: "urn:nuance-mix:tag:tuning:lang/coffee_app/coffee_rules/en-us/mix.tts?type=textruleset"

Upload audio

Follow these steps to upload an audio wave file. See Audio file.

  1. Open the shell script or batch file and edit the arguments for uploading an audio file, for example:

    ...
    python3 storage-client.py --server_url tts.api.nuance.com --token $MY_TOKEN \
    --upload --type wav --file resources/beep.wav \
    --context_tag coffee_app --name beep
    ...
    python storage-client.py --server_url tts.api.nuance.com --token %MY_TOKEN% ^
    --upload --type wav --file ..\resources\beep.wav ^
    --context_tag coffee_app --name beep
  2. Run the client using the shell script or batch file to upload the audio file.

    ./run-storage-client.sh
    run-storage-client.bat

The client uploads the WAV file to Mix storage. To use this audio recording in your synthesis requests, reference it using the URN returned. The type=wav field is for information only and is not required as part of the reference.

2023-06-22 18:07:17,548 INFO  Type is Wav
2023-06-22 18:07:17,782 INFO  Done reading data
2023-06-22 18:07:17,835 INFO  status {
  status_code: OK
}
uri: "urn:nuance-mix:tag:tuning:audio/coffee_app/beep/mix.tts?type=wav"

Delete resource

If you need to remove a resource from storage, include the --delete option and the resource URN.

  1. Open the shell script or batch file and edit the argument for deleting a resource. For example, this removes a previously-uploaded ruleset:

    ...
    python3 storage-client.py --server_url tts.api.nuance.com --token $MY_TOKEN \
    --delete \
    --uri urn:nuance-mix:tag:tuning:lang/coffee_app/coffee_rules/en-us/mix.tts
    ...
    python storage-client.py --server_url tts.api.nuance.com --token %MY_TOKEN% ^
    --delete ^
    --uri urn:nuance-mix:tag:tuning:lang/coffee_app/coffee_rules/en-us/mix.tts
  2. Run the client using the script or batch file to delete the resource.

    ./run-storage-client.sh
    run-storage-client.bat

The client removes the object from Mix storage and returns a status code.

2023-06-22 18:23:59,353 INFO  status {
  status_code: OK
}