Sizemore

Head of Narrative

"...a relentless, fucking, experience"

Install

$ yarn add dataplor/sizemore

const { configure,loadExpressions } = require('sizemore');

configure({
  bucket: 'somebucket',
  repo: 'scripts',
  repoOwner: 'mycompany',
  scriptsPath: 'src',
});

const callData = JSON.parse(message.body);

return loadExpressions({
  ref:         callData.script.commit,
  voiceConfig: callData.call.voice,
  data:        callData.call.data,
  verifying:   callData.call.contexts.map(c => c.attribute),
}).then( expressionSet => {
  expressionSet.loadAudio().then(() => {
    // some stuff
    // then!
    const frame = expressionSet.getExpression("hello").audio.slice(0,320)
    ws.send(frame)
      
    );
  });
});

ENV

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
GITHUB_PERSONAL_ACCESS_TOKEN

Definitions

• key: a unique string that represents something the bot might say, ie "hello", or "verify_name"
• Line: A single phrase associated with a key. The phrase includes placeholders for data and must be supplied with that data to be ready to deploy.
• Script: A collection of Lines that make up the generic vocabulary of the bot.
• Expression: A single phrase associated with a key, but distinct from a Line in that the placeholders have been filled in by the data for this particular record.
• ExpressionSet: A collection of Expressions

API

loadExpressions(ref: string, voiceConfig: object, data: object, verifying: array)

Returns a Promise that resolves with an ExpressionSet ready to use. Fetch scripts from central repository, create an ExpressionSet with an Expression for each Line in the Script.

const callData = JSON.parse(message.body);
loadExpressions({
  voiceConfig: callData.voice,
  data:        callData.data,
  verifying:   callData.contexts.map(c => c.attribute),
}).then( expressionSet => {
  // do things with the expressionSet
})

| Attribute | Type | Required | Description | | --------- | ------- | ------------- | ------------------------------------------ | | ref | string | optional | A git ref for the script repo, which is usually a commit SHA. If omitted, it will fetch the latest scripts. | | voiceConfig | object | required | | | voiceConfig.provider | string | required | Voice synthesis provider, ie aws | | voiceConfig.voice | string | required | ID of the voice to use, ie Lupe | | voiceConfig.locale | string | required | Valid locale string, ie es-US | | data | object | required | An object with the data for this record, ie {name: "foo"} | | verifying | array[string] | required | An array of strings of attributes which are being verified by this call, ie ["name"] |

ExpressionSet

A wrapper for a collection of expressions. By default, the scripts are fetched but the audio is not. You must call loadAudio to add the binary audio streams to the Expressions

Attributes

| Attribute | Type | Description | | --------- | ------- | ------------------------------------------ | | commit | string | git SHA that represents the "version" of the Script | | script | object | Script object | | voiceConfig | object | same three keys as above: provider,voice,locale | | data | object | Data provided to Lines to turn them into Expressions | | verifying | array[string] | Attributes this call is verifying, used to determine which Lines/Expressions can be skipped. | | data | object | An object with the data for this record, ie {name: "foo"} | | verifying | array[string] | An array of strings of attributes which are being verified by this call, ie ["name"] | | expressions | object | Object of expressions by key |

Methods

getExpression(key string)

const expression = expressionSet.getExpression('hello');
expression.key  // => "hello"
expression.text // => "¡Hola!"

Fetch a specific Expression by its key.

loadAudio()

expressionSet.loadAudio().then(() => {
  // audio is ready!
  expressionSet.getExpression('hello').audio.pipe(somewhere)
});

Have all Expressions fetch pre-synthesized binary Audio from s3. Returns a promise with no resolution value.

Expression

An object containing all the information about a single phrase the bot can say.

Attributes

| Attribute | Type | Description | | --------- | ------- | ------------------------------------------ | | key | string | ie 'hello' or 'verify_name' | | commit | string | git SHA that represents the "version" of the Script | | line | object | Line object | | voice | string | from voiceConfig, ie "Lupe" | | provider | string | from voiceConfig, ie "aws" | | locale | string | from voiceConfig, ie "es-US" | | data | object | An object with all the data for this record, ie {name: "foo"} | | ssml | string | Interpolated string taking the template from this.line.ssml and interpolating using this.data, ie "<speak><prosody rate=\"110%\">¿Estoy marcando a Ryan Taco?</prosody></speak>" | | text | string | Interpolated string taking the template from this.line.text and interpolating using this.data, ie "¿Estoy marcando a Ryan Taco?" | | filename | string | filename of the audio on s3, which is a hashed function of ssml,voice,provider,locale | | s3Key | string | Key of the audio on s3, includes full path unlike filename, ie "expressions/4128ab87ef...809a9b08ce8.mp3" | | audio | ArrayBuffer | binary audio data, in wav PCM format. Not set until loadAudio() is called on this Expression or parent ExpressionSet |

Methods

toJSON()

const expression = expressionSet.getExpression('hello');
expression.toJSON()  // => {key, ssml, text, voice, provider, locale}

Return a plain JS object with the key, ssml, text, voice, provider, locale.

loadAudio()

const expression = expressionSet.getExpression('hello');
expression.loadAudio().then(() => {
  const msg = expression.audio.slice(0,320);
  ws.send(msg)
});

Returns a promise with no resolution value. Fetch audio from S3, convert it from mp3 to PCM wav and store it on this instance as this.audio as an ArrayBuffer.

fetchScripts(ref: string, locale: string)

Returns a Promise that resolves with a plain JS Script object. Usually you want to loadExpressions but if you want the scripts by themselves you can get them here.

fetchScripts({locale: 'es-US', ref: '72e4defe85961d7d3986f02a262d8002c7257449'}).then( script => {
  // do things with the script
  script['hello'] 
  // => {
  //  "required": true,
  //  "ssml": "<speak><prosody rate=\"110%\">¡Hola!</prosody></speak>",
  //  "text": "¡Hola!" 
  //}
})

| Attribute | Type | Required | Description | | --------- | ------- | ------------- | ------------------------------------------ | | ref | string | optional | A git ref for the script repo, which is usually a commit SHA. If omitted, it will fetch the latest scripts. | | locale | string | required | Valid locale string, ie es-US |

hashExpression(expression Expression)

Returns a SHA512 hash unique to this Expression's ssml, locale, voice and provider. Why a long ass 512 hash? I really don't want collisions.

hashExpression(expression) // => "0153d6c2914f8b9dfbd773c41986e412ede26d3f01e7441b600049a527912097d233385036fd4ff34369f5915c74929126d9bff78e962ff24410374bfbedda78"

| Attribute | Type | Required | Description | | --------- | ------- | ------------- | ------------------------------------------ | | expression | Expression | required | An expression to hash |

hashedFilename(expression Expression,extension string)

Returns a SHA512 hash unique to this Expression's ssml, locale, voice and provider. Why a long ass 512 hash? I really don't want collisions.

hashedFilename(expression) // => "0153d6c2914f8b9dfbd773c41986e412ede26d3f01e7441b600049a527912097d233385036fd4ff34369f5915c74929126d9bff78e962ff24410374bfbedda78.mp3"

| Attribute | Type | Required | Description | | --------- | ------- | ------------- | ------------------------------------------ | | expression | Expression | required | An expression to hash | | extension | string | optional | Defaults to .mp3 |

You wanted me? Well let this be a lesson!

And the lesson is: If you're looking for a reckoning, a reckoning is what you'll find! If you're looking for a villain, then I'm your man! But look at yourselves. This world you built is bound by villainy. You sleep on the broken bodies of the ones who were here before you. Warm yourselves with their embers! Plow their bones into your fields! You paid them for this land with lead, and I'll pay you back in full!

You wanted me??? Well all I can say to that is, here I fucking am!

https://www.youtube.com/watch?v=T1de3dRPyiY