{"_id":"@caspingus/ssml-check","name":"@caspingus/ssml-check","dist-tags":{"latest":"0.4.6"},"versions":{"0.4.6":{"name":"@caspingus/ssml-check","version":"0.4.6","description":"Check for valid SSML","main":"index.js","devDependencies":{"webpack":"^5.88.2","webpack-cli":"^5.1.4"},"scripts":{"dev":"npm install && webpack watch --mode development --devtool eval-source-map","prod":"npm install && webpack --mode production"},"dependencies":{"@caspingus/ssml-check-core":"^0.3.9","assert":"^2.1.0","buffer":"^6.0.3","fs":"^0.0.1-security","http":"^0.0.1-security","music-metadata":"^3.5.3","path":"^0.12.7","stream":"^0.0.2","stream-browserify":"^3.0.0","string_decoder":"^1.3.0","url":"^0.11.3","xml-js":"^1.6.11"},"repository":{"type":"git","url":"git+https://github.com/michaelsharman/ssml-check.git"},"keywords":["ssml","alexa","google","voice","speech","amazon alexa","google assistant","vui"],"license":"MIT","bugs":{"url":"https://github.com/michaelsharman/ssml-check/issues"},"types":"./index.d.ts","_id":"@caspingus/ssml-check@0.4.6","gitHead":"a8607a8015c07769000bdbcbd2300b4fb2d1d69c","homepage":"https://github.com/michaelsharman/ssml-check#readme","_nodeVersion":"22.1.0","_npmVersion":"10.8.3","dist":{"integrity":"sha512-MpAmabg8j+DpHZdB9k7773EvvXlvS5Q9BW2IZRG4XgYUyEgLoofHYvwWKhH561cJ3SXTTaRopBxKLDs4yaYa0A==","shasum":"b7d6f4d9b73bf66c39072edb0e896dc9a00fe102","tarball":"https://registry.npmjs.org/@caspingus/ssml-check/-/ssml-check-0.4.6.tgz","fileCount":18,"unpackedSize":54975,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCICnqHpgjOfGXHwmXraY+VDPY3TwO67khK5Gs+gQSqmdHAiEAluCm9ISoXKehRKv/6YA7/Ak4krVVGfiEo6U8W5E9ZRE="}]},"_npmUser":{"name":"caspingus","email":"michael@learnosity.com"},"directories":{},"maintainers":[{"name":"caspingus","email":"michael@learnosity.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/ssml-check_0.4.6_1726726526799_0.3859137679592055"},"_hasShrinkwrap":false}},"time":{"created":"2024-09-19T06:15:26.711Z","0.4.6":"2024-09-19T06:15:26.945Z","modified":"2024-09-19T06:15:27.222Z"},"maintainers":[{"name":"caspingus","email":"michael@learnosity.com"}],"description":"Check for valid SSML","homepage":"https://github.com/michaelsharman/ssml-check#readme","keywords":["ssml","alexa","google","voice","speech","amazon alexa","google assistant","vui"],"repository":{"type":"git","url":"git+https://github.com/michaelsharman/ssml-check.git"},"bugs":{"url":"https://github.com/michaelsharman/ssml-check/issues"},"license":"MIT","readme":"# SSML-Check\n\nSSML-Check will verify that a given input is valid SSML. It is built on top of [ssml-check-core](https://www.npmjs.com/package/ssml-check-core), which provides core syntax validation of SSML. This library extends this functionality by looking into files accessed by the input SSML such as audio files to make sure they conform with platform expectations.\n\n# Usage\n\nThis library exposes two functions which allow you to check and optionally correct a given SSML string\n\n## Check\nThe first is `check` which verifies whether the given input is a valid SSML string on either the Amazon Alexa or Google Assistant platform (or both). This function returns a Promise with an array of errors indicating how the input fails validation, or a Promise of undefined if there are no errors.\n\n```\ncheck(ssml, options)\n```\n\nThe arguments to this function are:\n\n * ssml - The SSML to check\n * options - Options for evaluating the SSML as noted below\n \nThe options structure is composed of the following fields with the following default values:\n\n```\n{\n  platform:all,              // The voice platform to evaluate this SSML against.\n                             // Valid values are \"all\", \"amazon\", or \"google\".\n  locale:undefined,          // The locale you want to check against, used for certain\n                             // locale-specific attributes like amazon:emotion\n  validateAudioFiles:false,  // Whether to validate audio files against\n                             // acceptable formats (bit rate, sample rate, etc)\n  getPositions:false,        // If set, the index of the tag will be returned as the position\n                             // field within the error object\n  unsupportedTags:undefined, // An array of tags that will be flagged as invalid\n                             // For example, ['prosody']\n}\n```\n\nThe return value is a Promise resolving to an array of errors that were encountered in processing the SSML, or `undefined` if no errors were encountered.  The format of each error object is as follows:\n\n```\n{\n  type,       // The type of error encountered (\"tag,\" \"audio\" or a specific error)\n  tag,        // The tag that had an error (set if type is \"tag\")\n  attribute,  // The attribute that had an error (set if type is \"tag\")\n  value,      // The attribute value that was in error (set if type is \"tag\" or \"audio\")\n  detail,     // Further details about the error (set if type is \"audio\")\n  position,   // The position of the start of the tag within the input string (set if getPositions is true)\n}\n```\nThe current version of ssml-check will check for the following:\n\n * Valid XML format\n * All tags are valid tags for their platform with valid attributes and values\n * No more than five `audio` tags in the response\n * Note invalid & character\n * Valid audio file format (HTTPS, MP3, length, bit rate, sample rate), if validateAudioFiles is set\n \n### Examples\n\n```\nconst ssmlCheck = require('ssml-check');\nssmlCheck.check('<speak><prosody rate=\"5%\">Hello world</prosody></speak>')\n.then((errors) => {\n  if (errors) {\n    console.log(JSON.stringify(errors));\n  } else {\n    console.log('SSML is clean');\n  }\n});\n```\nwill output `[{\"type\":\"tag\",\"tag\":\"prosody\",\"attribute\":\"rate\",\"value\":\"5%\"}]`\n\n```\nconst ssmlCheck = require('ssml-check');\nssmlCheck.check('<speak><audio src=\"https://foo.mp3\"/></speak>', {validateAudioFiles: true})\n.then((errors) => {\n  if (errors) {\n    console.log(JSON.stringify(errors));\n  } else {\n    console.log('SSML is clean');\n  }\n});\n```\nwill output `[{\"type\":\"audio\",\"value\":\"https://foo.mp3\",\"detail\":\"Can't access file\"}]`\n\n\n## verifyAndFix \nThe second function is `verifyAndFix` which returns a Promise of an object containing an array of caught SSML errors (similar to check) and, if possible, corrected SSML as noted below.\n\n```\nverifyAndFix(ssml, options)\n```\n\nThe arguments to this function, including the options structure, are the same as for check.\n\nThe return value is a Promise resolving to an object with the following fields:\n\n```\n{\n  fixedSSML,  // A fixed SSML string if errors are found that can be corrected for\n              // This field will be undefined if the SSML cannot be corrected\n  errors,     // An array of errors. The format of each object in this array is as\n              // defined above for the check function. This field is undefined\n              // if there are no errors.    \n}\n```\n\nIf there are no errors, then the Promise will contain an empty object.\n\nThe current version of ssml-check will correct the following errors:\n\n * If more than five `audio` tags are in the response, elements after the first five are removed\n * If an invalid audio file is found when the validateAudioFiles option is set, the element will be removed \n * If an invalid tag is found, the element will be removed  \n * If an invalid attribute is found, it will be removed (in the case of the src attribute for audio, if this is missing or invalid the element will be removed)\n * If an invalid value is found for an attribute within a valid tag, the value will be corrected as best possible. For example, adding a leading + to values that require it like prosody's pitch attribute, adjusting the value to be within an acceptable range, or substituting a default value if necessary \n\n### Examples\n\n```\nconst ssmlCheck = require('ssml-check');\nssmlCheck.verifyAndFix('<speak><audio src=\"https://foo.mp3\"/>This & that</speak>', {validateAudioFiles: true})\n.then((result) => {\n  if (result.fixedSSML) {\n    console.log(result.fixedSSML);\n  } else if (result.errors) {\n    console.log(JSON.stringify(result.errors));\n  } else {\n    console.log('SSML is clean');\n  }\n});\n```\nwill output `<speak>This &amp; that</speak>`\n\n```\nconst ssmlCheck = require('ssml-check');\nssmlCheck.verifyAndFix('<speak><tag><prosody rate=\"60\">Hello world</prosody></tag></speak>')\n.then((result) => {\n  if (result.fixedSSML) {\n    console.log(result.fixedSSML);\n  } else if (result.errors) {\n    console.log(JSON.stringify(result.errors));\n  } else {\n    console.log('SSML is clean');\n  }\n});\n```\nwill output `<speak><prosody rate=\"60%\">Hello world</prosody></speak>`\n\n# Contributions\n\nWe love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:\n\n- Reporting a bug\n- Discussing the current state of the code\n- Submitting a fix\n- Proposing new features\n\nWhen contributing to this repository, please first discuss the change you wish to make by raising an issue or sending an e-mail with to the owners of this repository.\n","readmeFilename":"README.md"}