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:

Python 3.6 or later.
The generated Python stub files from gRPC setup.
Your client ID and secret from Prerequisites from Mix.
The Python client files: sample-storage-client.zip

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

import argparse
import sys
import time
import logging
import grpc
import os
import json
import math
from google.protobuf import text_format

from nuance.tts.storage.v1beta1.storage_pb2 import *
from nuance.tts.storage.v1beta1.storage_pb2_grpc import *

args = None

def parse_args():
    global args
    parser = argparse.ArgumentParser(
        prog="storage-client.py",
        usage="%(prog)s [-options]",
        add_help=False,
        formatter_class=lambda prog: argparse.HelpFormatter(
            prog, max_help_position=45, width=100)
    )

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

def create_channel():
    call_credentials = None
    channel = None

    call_credentials = grpc.access_token_call_credentials(args.token)
    channel_credentials = grpc.composite_channel_credentials(grpc.ssl_channel_credentials(), call_credentials)

    return grpc.secure_channel(args.server_url, credentials=channel_credentials)

# Reads the input file in chunks
def read_file(file, context_tag, name, type, voice, voice_model, voice_version, vocalizer_studio_version, language, max_chunk_size_bytes=4096):

    file_handle = open(file, "rb")

    upload_request = UploadRequest()
    upload_init_message = UploadInitMessage()
    upload_init_message.context_tag = args.context_tag
    upload_init_message.name = args.name

    if type == 'activeprompt':
        log.info('Type is ActivePromptDB')
        active_prompt_db = ActivePromptDB()
        active_prompt_db.voice = voice
        active_prompt_db.voice_model = voice_model
        active_prompt_db.voice_version = voice_version
        active_prompt_db.vocalizer_studio_version = vocalizer_studio_version
        upload_init_message.active_prompt_db.CopyFrom(active_prompt_db)
    elif type == "user_dictionary":
        log.info('Type is User Dictionary')
        user_dictionary = UserDictionary()
        user_dictionary.language = language
        upload_init_message.dictionary.CopyFrom(user_dictionary)
    elif type == "text_ruleset":
        log.info('Type is Text User Ruleset')
        text_ruleset = TextUserRuleset()
        text_ruleset.language = language
        upload_init_message.text_ruleset.CopyFrom(text_ruleset)
    elif type == "wav":
        log.info('Type is Wav')
        wav = Wav()
        upload_init_message.wav.CopyFrom(wav)

    upload_request.upload_init_message.CopyFrom(upload_init_message)
    yield upload_request

    while True:
        data = file_handle.read(max_chunk_size_bytes)
        if not data:
            log.info("Done reading data")
            break
        upload_request = UploadRequest()
        upload_request.data_chunk = data
        yield upload_request

def validate_resource_arguments(args):
    if args.type != "activeprompt" and args.type != "user_dictionary" and args.type != "text_ruleset" and args.type != "wav":
        log.error("Invalid resource type [%s]. Must be one of: [activeprompt, user_dictionary, text_ruleset, wav]" % args.type)
        return False

    if args.type == "activeprompt":
        if not args.voice:
            log.error("Missing voice for type=activeprompt")
            return False
        elif not args.voice_model:
            log.error("Missing voice_model for type=activeprompt")
            return False
        elif not args.voice_version:
            log.error("Missing voice_version for type=activeprompt")
            return False
        elif not args.vocalizer_studio_version:
            log.error("Missing vocalizer_studio_version for type=activeprompt")
            return False
    elif args.type == "user_dictionary" and not args.language:
        log.error("Missing language for type=user_dictionary")
        return False
    elif args.type == "text_ruleset" and not args.language:
        log.error("Missing language for type=text_ruleset")
        return False

    return True

def run():
    parse_args()

    log_level = logging.DEBUG
    global log
    log = logging.getLogger('')
    logging.basicConfig(format='%(asctime)s %(levelname)-5s %(message)s', level=log_level)

    if args.upload and args.delete:
        log.error("--upload and --delete are mutually exclusive: choose only one operation at a time")
        return

    if args.upload:

        if not args.file:
            log.error("Missing file")
            return
        elif not args.context_tag:
            log.error("Missing context tag")
            return
        elif not args.name:
            log.error("Missing resource name")
            return

        if not os.path.exists(args.file):
            log.error("File [%s] does not exist" % args.file)
            return

        if not os.path.isfile(args.file):
            log.error("File [%s] is not a file" % args.file)
            return

        if not validate_resource_arguments(args):
            return

        with create_channel() as channel:
            storage_stub = StorageStub(channel)
            request_iterator = read_file(file=args.file, context_tag=args.context_tag, name=args.name, type=args.type, voice=args.voice, voice_model=args.voice_model, voice_version=args.voice_version, vocalizer_studio_version=args.vocalizer_studio_version, language=args.language, max_chunk_size_bytes=args.max_chunk_size_bytes)
            upload_response = storage_stub.Upload(request_iterator)
            log.info(text_format.MessageToString(upload_response))
    elif args.delete:
        if not args.uri:
            log.error("Missing URI for deletion")
            return

        with create_channel() as channel:
            storage_stub = StorageStub(channel)
            delete_request = DeleteRequest()
            delete_request.uri = args.uri
            delete_response = storage_stub.Delete(delete_request)
            log.info(text_format.MessageToString(delete_response))
    else:
        log.error("Missing operation flag: must set either --upload or --delete")
        return


if __name__ == '__main__':
    run()

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.

Linux: run-storage-client.sh
Windows: run-storage-client.bat

#!/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.

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

Linux: run-storage-client.sh
Windows: run-storage-client.bat

...
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

Run the client using the shell script or batch file to upload the user dictionary.
- Linux
- Windows
```
./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.

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

Linux: run-storage-client.sh
Windows: run-storage-client.bat

...
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

Run the client using the shell script or batch file to upload the ActivePrompt database.
- Linux
- Windows
```
./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.

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

Linux: run-storage-client.sh
Windows: run-storage-client.bat

...
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

Run the client using the shell script or batch file to upload the ruleset.
- Linux
- Windows
```
./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.

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

Linux: run-storage-client.sh
Windows: run-storage-client.bat

...
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

Run the client using the shell script or batch file to upload the audio file.
- Linux
- Windows
```
./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.

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

Linux: run-storage-client.sh
Windows: run-storage-client.bat

...
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

Run the client using the script or batch file to delete the resource.
- Linux
- Windows
```
./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
}

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.