@dataplor/sizemore

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