Web components for Attendi's speech service.
npm install @attendi/speech-serviceThis package provides multiple webcomponents to facilitate recording and transcribing audio.
The webcomponents are available as an npm package or from CDN.
To install with npm, run:
``bash`
npm install @attendi/speech-service
To import the functionality into your project, add
`javascript`
import "@attendi/speech-service";
to the page in which you want to use the components.
The package is also available as pre-built, single-file bundles. These are provided for more flexibility around development workflows: for example, if you would prefer to download a single file rather than use npm and build tools. The bundles are standard JavaScript modules with no dependencies - any modern browser should be able to import and run the bundles from within a
`
If you're using npm for client-side dependencies, you should use the npm package, not these bundles. The bundles intentionally combine the dependencies into a single file, which can cause your page to download more code than it needs.
Components refer to webcomponents that can be used in HTML. They are custom HTML tags that can be used to add functionality to a webpage.
After the import, Attendi's microphone component becomes available as a custom HTML tag:
`html`
TL;DR:
> This component provides a UI for recording, takes care of recording audio and processing it. The component is built with extensibility in mind. It can be extended with plugins that add functionality to the component using the component's plugin APIs. Arbitrary logic can for instance be executed at certain points in the component's lifecycle, such as before recording starts, or when an error occurs.
The AttendiMicrophone component is a button that can be used to record audio.
Its curresponding HTML tag is .start
Recording is started by clicking the button, and the recording can be stopped by
clicking the button again. The same can be accomplished programmatically by calling
its and stop methods.
The component is built with extensibility in mind. It can be extended with plugins that
add functionality to the component using the component's plugin APIs. Arbitrary logic can
for instance be executed at certain points in the component's lifecycle, such as before
recording starts, or when an error occurs, by registering callbacks with the functions
in its hooks object, or using the microphone's other methods. See theAttendiMicrophonePlugin interface for more information. More information about
the plugin APIs and available plugins can be found below.
#### Attributes
Other important attributes that can be set on the component are:
- base-color: Only accepts HEX string, e.g. "#ff1234". The component will be themed with various shades of this color.volume-feedback-type
If not set, a default color scheme will be used.
- : The component can show a visual feedback of the volumeouter
to make it clear to the user that the microphone is working. This option specified
how the feedback should be shown. Currently, the only supported values are andinner
. outer will show a colored area outside the component. It will therefore need some paddinginner
on the outside. will fill a percentage of the microphone icon depending on the volume.inner
The default value is .outer-volume-feedback-type
- : If volume-feedback-type is set to outer, thisall
attribute can be used to specify which side of the component should show the feedback.
The default value is , which will show the feedback on all sides. Otherleft
supported values are , right, top, and bottom.show-options
- : If set to true, the component will show the options button.false
Currently the options include the ability to report using either the SOEP or
the SOAP reporting method. If set to , the component will not show thedefault-plugins
options button.
- : The component uses a plugin system to extend its functionality. Previously,notification-audio
some plugins were always added. As this constrains the microphone to a specific set of use cases, we intend
to remove this behavior. To maintain backwards compatibility in the meantime, it is possible to
specify a list of default plugins. By default, the following plugins are added (mostly for backwards compatibility):
- : Play a sound when the microphone starts, stops, or encounters an error.volume-feedback
- : Show volume feedback animation in the microphone when recording.attendi-transcribe
- : Transcribe recorded audio using the Attendi Speech Service when stoppinglinear-reporting-method
the recording.
- : Add menu options for using linear reporting methodsSOEP
(, SOAP, and TIME).error
- : Show an error dialog and play an error sound when an error occurs. If thesilent
attribute is set to true, will not play the error sound.
If no plugins should be added, set the default-plugins attribute to an empty list.
Example:
`html
`
- : The media track constraints for the audio track to use when { noiseSuppression: true, echoCancellation: true, autoGainControl: true }
requesting the microphone. See {@link MediaTrackConstraints} or the
MediaTrackConstraints documentation
for more information. Especially on lower end devices, turning off noise suppression
and echo cancellation can improve the quality of the recording since it reduces CPU
usage. Any CPU-intensive tasks increase the risk of thread scheduling issues. This in turn
can cause some audio buffers to be dropped, resulting in audio glitches. Not all
browsers support changing these constraints, so they may not always be respected. In that
case, the component will fall back to the default constraints and log a warning.
If left empty, the browser's default constraints will be used.
The default constraints are generally (but not always):
. As explained noiseSuppression
above, setting to false and/or echoCancellation to false can stay-large
improve the quality of the recording since it reduces CPU usage.
- : By default, the component will shrink to a smaller size whentrue
recording. If set to , the component will stay at the same size when recording.no-volume-feedback
- (deprecated): If set to true, the component will not show any volumedefault-plugins
feedback. Mostly here for backwards compatibility. The preferred way to disable volume feedback
is to set the attribute to a list excluding volume-feedback.silent
- (deprecated): By default, the component will play a sound when the recording isnotification-audio
started and stopped, and when an error occurs, as we add the plugindefault-plugins
as one of the . This can be disabled by setting this attribute to true, so thatdefault-plugins
no audio files are loaded or played. The preferred approach is to explicitly set the
attribute to a list excluding . It is then possible to supply your own plugin totranscribe-api-config
play audio at the appropriate moments. If content security policies are an issue, you can override
the URLs used to load the audio files from.
- (deprecated): See the documentation for the ITranscribeAPIConfig
interface for more information on the expected structure. The attribute's value should be a serialized JSON string.
Before version 0.14.0, this attribute was used to configure the microphone to connect with Attendi's APIs.
This is still necessary if or linear-reporting-method is in the list of default-plugins (which is the case if youdefault-plugins="[]"
don't set ; see attribute default-plugins for more information).
Instead, it is recommended to always add a transcription plugin
manually. For example, if you want to connect with the transcription API from the frontend:
`html`
In the deprecated approach (not recommended anymore), you would set the transcribe-api-config attribute to a JSON string
or set the property directly:
`html
>
>
`
or through setting the transcribeAPIConfig property directly:
`javascript
const transcribeAPIConfig = {
customerKey: "ck_12345",
userId: "myUser-1",
unitId: "myUnit-1",
modelType: "ResidentialCare",
};
const mic = document.querySelector("attendi-microphone");
// At initialization, set the config.
mic.transcribeAPIConfig = transcribeAPIConfig;
`
To set a boolean attribute to true, you can simply set the attribute without a value:
`html`
#### Plugins
The component can be extended with plugins that add functionality to the component. The
general approach is to register callbacks at specific lifecycle events, such as when recording
starts, stops, or when an error occurs. The component will call these callbacks at the appropriate
times. Other functionality can be added as well. The plugin APIs are not fully stable yet, so use
with caution. The plugin APIs we list below are more stable.
##### Adding and activating plugins
We recommend setting the default-plugins attribute to an empty list, and adding all the plugins you needdefault-plugins
manually. In time, we will change to be an empty list by default. This also gives youattendiMicrophonePlugins
more control over the plugins that are added to the microphone. The library exposes a object
that contains all the available plugins. Add these plugins to the microphone as follows:
`html
`
Note that the order in which the plugins are added is important, as the added lifecycle hooks will be called in the order
in which the plugins were added. For instance, the NotificationAudioPlugin and AttendiTranscribePlugin plugins bothonStopRecording
add a hook to the event. If the NotificationAudioPlugin is added after the AttendiTranscribePlugin,NotificationAudioPlugin
the stop notification sound will only be played after the transcription is done, while we want the sound to play when the
user clicks the button. Therefore we add the first here.
##### Creating a plugin
Warning: the microphone's plugin APIs are still under development and subject to change.
A plugin is a class that implements the AttendiMicrophonePlugin interface.
The functionality of any plugin is implemented in its activate method.AttendiMicrophone.plugins.activate
This method is called when the method is called, which allows itAttendiMicrophonePlugin.deactivate
to modify the microphone's behavior by calling plugin APIs. Any logic that needs to run when the
microphone is removed from the document's DOM should be implemented in the method.
This might for instance be necessary when the plugin changes some global state.
As an example, we could create a plugin that logs the length of the recorded audio when recording stops
as follows:
`typescriptThe recorded audio buffer has length ${buffer.length}
class LogBufferSizePlugin : AttendiMicrophonePlugin {
activate(mic: AttendiMicrophone) {
mic.hooks.onStopRecording((buffer) => {
console.log();`
});
}
}
We could then add this plugin to the microphone as follows:
`html
`
Notice from the example that we register the plugin with a name, and that we have to
call mic.plugins.activate() to activate the added plugin(s).
It is not strictly necessary to use plugins to call the plugin APIs. For instance, we
can accomplish the same thing as in the example above by calling the onStopRecording hook
directly:
`html
`
which can be preferable for simple use cases. For more complex use cases, plugins can be
a good way to structure the code, and to maintain state in the plugin object.
##### Hooks
The microphone component contains a hooks object with multiple functions to add lifecycle hooks.mic.hooks.onFirstClick(() => console.log("Recording will start soon!"));
Call them like so: .
All plugin API functions return a function that can be called to undo the registration:
`javascript`
const removeOnFirstClick = mic.hooks.onFirstClick(() => console.log("Recording will start soon!"));
removeOnFirstClick(); // The callback will no longer be called.
The following hooks are supported:
- onFirstClick: Called when the microphone is clicked for the first time. Some browsers like SafarionUIState
require a user interaction before some actions can be performed, like starting a recording or playing
a sound.
- : Called when the UI state of the microphone changes. Takes the new state as the first argument.NotStartedRecording
The UI state can be one of the following:
- : The microphone is not recording and is not processing a recording.LoadingBeforeRecording
- : The microphone is not recording, but is processing a recording.Recording
- : The microphone is recording.ProcessingRecording
- : The microphone is processing a recording.onAudioFrames
- : Called when audio frames are available. Takes as first argument the audio frames, which is a Float32Array of audio samples with values between -1 and 1. Callbacks registered with this hook will be called whenever new audio frames are available during recording. This can be used to do something with the audio in real-time.onBeforeStartRecording
- : Called before recording starts.onStartRecording
- : Called when recording starts.onBeforeStopRecording
- : Called before recording stops. Takes as first argument the recorded audio buffer,AttendiMicrophoneStopParameters
and as second argument the parameters that were used to stop the recording (see ).onStopRecording
- : Called when recording stops. Takes as first argument the recorded audio buffer,AttendiMicrophoneStopParameters
and as second argument the parameters that were used to stop the recording (see ).Float32Array
This can be used to do something with the recorded audio, like transcribing it. The given buffer is a .onError
- (unstable): Called when an error occurs.onAttributeChanged
- (unstable): Called when an attribute changes. Takes as arguments the name of the attribute,onPropertiesChanged
the old value, and the new value.
- (unstable): Called when a property changes. Takes as argument a map of the changed properties.
While there are a couple more plugin APIs, these should be considered internal and are not documented here.
##### Existing plugins
This package exposes a couple of pre-built plugins. Before version 0.14.0, some of these were
included in the component by default. As this constrains the microphone to a specific set of use cases,
we allow changing this behavior by setting the default-plugins attribute. For backwards compatibility,
some of these plugins are still included by default (indicated with default in the following list).
The following plugins are available:
- NotificationAudioPlugin (default): Play a sound when the microphone starts, stops, or encounters an error.VolumeFeedbackPlugin
- (default): Show volume feedback animation in the microphone when recording.AttendiTranscribePlugin
- (default): Transcribe recorded audio using the Attendi Speech Service when stopping.LinearReportingMethodPlugin
- (default): Add menu options for using linear reporting methods used inSOEP
medical reporting such as , SOAP, and TIME.AttendiStreamingTranscribePlugin
- : Transcribe audio in real-time using the Attendi Speech Service.
#### Implementing streaming transcription
The simplest way to get started with streaming is to use the AttendiStreamingTranscribePlugin plugin. However,
a limitation of this plugin is that it sets up a connection to Attendi's servers directly from the frontend, which
exposes the customer key to the frontend. This can be okay depending on your exact use case, but is less secure. An
alternative is to set up a proxy server in your backend that forwards any messages from the client to Attendi's servers and vice versa. As this method requires a bit more flexibility, we recommend creating your own plugin for this purpose.
This package exposes a WebSocketAudioStreamingAdapter class and createStream function that can be used as a building block for creating this plugin, as it abstracts away some of the complexity of setting up a WebSocket connection and sending audio data. Its implementation and an example of usage can be found in the package's bundled source at /src/components/attendi-microphone/plugins/streaming-transcribe.ts.
#### Communicating with the component (events)
The component emits (custom) events to communicate with your application. Your application can then
take actions based on these events if necessary. The following events are emitted:
- attendi-microphone-ui-state-updated: When the UI state of the component changes, this event is emitted. The event contains the new UI state in e.detail. The possible values are NotStartedRecording, LoadingBeforeRecording, Recording, and ProcessingRecording.attendi-microphone-volume-updated
- : Emitted when the volume level of the microphone changes. The event contains the volume level in e.detail.volume. It also contains the "raw" volume level in e.detail.rawVolume. The volume level scales and normalizes the raw volume level such that it is in the range [0, 1] and the highs are clearly separated from the lows. You would usually want to use the volume value.volume
detail contains a property .attendi-speech-service-error
- (unstable API): Emitted when an error is thrown within the component. This allows for error handling outside of the component. The event contains error type in e.detail.error. For more detailed information on the error, check e.detail.fullError.
If the default AttendiTranscribePlugin is used and transcribe-api-config is set on the component (deprecated),
the component will emit the following events:
- attendi-speech-segment: Emitted when the audio transcript is available. The event contains the transcript data, which can be accessed as e.detail.transcript.attendi-speech-service-done
- (DEPRECATED, use attendi-speech-segment instead): same purpose as attendi-speech-segment.
#### Styling
The component can be further styled using the following CSS variables:
- --attendi-microphone-max-width: Controls the maximum width of the component. The value--attendi-border-radius
of this also depends on the component attribute "show-options", since these
control whether the component will show an options button.
-
- (equivalent to --attendi-border-radius)--attendi-microphone-border-top-left-radius
-
-
-
-
-
-
-
-
-
-
For fine-grained control over the color theming, the microphone exposes a colorTheme property.
The color theme is an object with the following structure:
`typescript`
interface AttendiMicrophoneColorTheme {
fill: {
default: {
enabled: ColorValueHex;
hover: ColorValueHex;
active: ColorValueHex;
disabled: ColorValueHex;
};
active: {
enabled: ColorValueHex;
hover: ColorValueHex;
active: ColorValueHex;
disabled: ColorValueHex;
};
};
outline: {
default: {
enabled: ColorValueHex;
hover: ColorValueHex;
active: ColorValueHex;
disabled: ColorValueHex;
};
active: {
enabled: ColorValueHex;
hover: ColorValueHex;
active: ColorValueHex;
disabled: ColorValueHex;
};
};
icon: {
default: {
enabled: ColorValueHex;
hover: ColorValueHex;
};
active: {
enabled: ColorValueHex;
hover: ColorValueHex;
};
};
// Only used for outer volume feedback
volumeFeedback: ColorValueHex;
}
Internally, the color theme is generated from a base-color attribute if it is supplied, or from a defaultcolorTheme
color theme. If you want to use a custom color theme, you can set the property on the component.
For instance, to change the icon color on hovering the button, you can do:
`javascript
// Important: color should be a HEX string, e.g. "#ff1234"
const newHoverColor = "#0000ff";
const attendiMicrophone = document.querySelector("attendi-microphone");
const newColorTheme = { ...attendiMicrophone.colorTheme };
newColorTheme.icon.default.hover = newHoverColor;
attendiMicrophone.colorTheme = newColorTheme;
`
To change the microphone icon, use the microphone-icon slot. Example:
`html
stroke="currentColor"
fill="url(#uniqueId)"
/>
fill-rule="evenodd"
clip-rule="evenodd"
d="..."
fill="currentColor"
/>
`
An SVG icon is recommended. By default, the Attendi Microphone shows the volume level
by filling the microphone icon accordingly. It normally does this by finding a linear
gradient def in the SVG icon and setting its offset to the volume level. Therefore it's
important to have your SVG icon follow the same structure:
- Add a linear gradient as in the example above. Make sure the stop tag has anid of microphoneFill.path
- Make sure the tag that represents the microphone cone has a fill attributelinearGradient
that references the id of the tag.
#### Configuration specification
To communicate with the Attendi transcription APIs, use the AttendiTranscribePlugin plugin.
On initialization, it expects a configuration object with the following structure:
`typescripthttps://api.attendi.nl
const attendiTranscribePluginConfig = {
apiURL: . If you want to use the sandbox environment, set this to https://sandbox.api.attendi.nl.
customerKey:
userId:
config: {
model: modelType, // Which model to use, e.g. ModelType.ResidentialCare or "ResidentialCare"
},
metadata: {
reportId:
},
unitId:
};
const attendiTranscribePlugin = new AttendiTranscribePlugin(
attendiTranscribePluginConfig,
(transcript) => {
// Do something with the transcript.
console.log(transcript);
}
);
`
#### Configuration specification (deprecated)
**This section is here for backwards compatibility. It is only applicable if you are not changing the
default-plugins attribute to exclude the attendi-transcribe plugin and are setting the transcribe-api-config attribute directly on the component.**
All communication with the Attendi Speech Service backend (e.g. sending audio, receiving transcript) is handled by the component. The component expects to receive an object consistent with the ITranscribeAPIConfig interface:
`typescripthttps://api.attendi.nl
interface ITranscribeAPIConfig {
customerKey: string; // Your customer API key, used to authenticate to Attendi APIs.
userId: string; // Unique id assigned (by you) to your user
unitId: string; // Unique id assigned (by you) to the team or location of your user
userAgent?: string; // User agent string identifying the user device, OS and browser. Defaults to navigator.userAgent
modelType?: ModelType; // Which model to use, e.g. ModelType.ResidentialCare or "ResidentialCare"
apiURL?: string; // URL of the Attendi Speech Service API. Defaults to . If you want to use the sandbox environment, set this to https://sandbox.api.attendi.nl.`
}
Here, ModelType is given by:
`typescript`
enum ModelType {
DistrictCare,
ResidentialCare,
}
or can be specified as the equivalent string, e.g. "ResidentialCare".
There are two ways to supply the configuration object to the component:
- Using the transcribe-api-config attribute on the html component, andtranscribeAPIConfig
- Manipulating the tag's property in Javascript.
You are free to choose the one that fits your needs best.
##### Configuration using the transcribe-api-config attribute
It is possible to supply the component with a JSON representation of the transcribe config like so:
`html`
>
More specifically:
`html`
>
This method is to be preferred when you are able to render HTML from a template. In React for example, you could do the following:
`javascript
import { ModelType } from "@attendi/speech-service";
function App() {
const transcribeAPIConfig = {
customerKey: "ck_12345",
userId: "myUser-1",
unitId: "myUnit-1",
modelType: ModelType.ResidentialCare,
};
const transcribeAPIConfigJSON = JSON.stringify(transcribeAPIConfig);
return (
##### Configuration by manipulating the tag's
property in JavascriptIf you're not able to render HTML tags dynamically, for example when using vanilla HTML and Javascript, set the tag's
transcribeAPIConfig property yourself. For example:`javascript
const attendiMicrophone = document.querySelector("attendi-microphone");
// at initialization, set the config
attendiMicrophone.transcribeAPIConfig = transcribeAPIConfig;
`$3
The
component visualizes the volume of an audio signal over time.
Its curresponding HTML tag is .
It displays a series of vertical bars whose heights correspond to the volume levels that
have been added to it using its addVolume method. These bars are updated at a rate that
is determined by update-period-milliseconds, creating a scrolling effect to the right.
Any volume value added within a single update period is binned and averaged over that period.
Any volume value outside of the range [0, 1] will raise an error.The component can be started and stopped using the
start and stop methods respectively. After
calling start, volume values need to be added using the addVolume method.
The reset method can be used to reset the volume bars after use.Other important attributes that can be set on the component are:
-
update-period-milliseconds: The time it takes before the volume bars are updated. The default value is 75ms.
- volume-bar-thickness-multiplier: Allows controlling the thickness of the volume bars.
Multiplies the default thickness of the volume bars. The default value is 1.
- running: Whether the volume bars are being updated or not. If true, the volume bars
will update at the frequency specified by the updatePeriodMilliseconds. No updates will be rendered.
Playback can be controlled by setting this attribute to true or false, or with this component's start
and methods.#### Styling attendi-volume-over-time
The component can be further styled with the following CSS variables:
-
--attendi-volume-over-time-background-color: The background color of the component. Transparent by default.
- --attendi-volume-over-time-border-radius: The border radius of the component. 0px by default.
- --attendi-volume-over-time-volume-bar-border-radius: The border radius of the volume bars. 2px by default.
- --attendi-volume-over-time-volume-bar-color: The color of the volume bars. #1c69e8 by default.#### Events
The component emits the following events:
-
attendi-volume-over-time-updated: Emitted when the volume bars are updated.
The event detail contains the volume bins (an array of numbers).#### Example
`html
volume-bar-thickness-multiplier="1"
>
`
#### Integration with the Attendi Microphone
The AttendiVolumeOverTime component can be used together with the AttendiMicrophone component to provide visual feedback of the volume level while recording. The AttendiMicrophone component emits events with volume data that can be used to update the AttendiVolumeOverTime component.
`html
`
This component is designed to be used within a modal. When it is opened, it will show text editor and audio recording controls. As this is quite a complex interaction, it is recommended to use the Attendi Microphone component instead. This component is planned to be deprecated in the future. Please use the Attendi Microphone component instead.
The recorder component and modal component are available as custom HTML tags:
`html`
The modal component is designed specifically for use with the Attendi Speech Service component. Its size and position adapts to the viewport size.
#### Communicating with the speech service component
The component emits events to communicate with your application. Your application is responsible for taking actions based on these events. The following events are emitted:
- attendi-speech-segment: Emitted when the audio transcript is available. The event contains the transcript data, which can be accessed as e.detail.transcript.attendi-speech-service-done
- (DEPRECATED, use attendi-speech-segment instead): same purpose as attendi-speech-segment.attendi-speech-service-cancel
- : Emitted when the user clicks the "exit" button, which is the X button on the topright corner of the component. This event should be handled by closing the view (e.g. modal) that contains the component.attendi-speech-service-error
- : Emitted when an error is thrown within the component. This allows for error handling outside of the component. The event contains error type in e.detail.error. For more detailed information on the error, check e.detail.fullError.
Example:
`javascript
let attendi_speech_service_element = document.querySelector(
"attendi-speech-service"
);
let transcript = "";
attendi_speech_service_element.addEventListener(
"attendi-speech-segment",
(e) => {
console.log(e);
transcript = e.detail.transcript;
}
);
// This event is fired when the "cancel" button is clicked.
attendi_speech_service.addEventListener(
"attendi-speech-service-cancel",
(_) => {
closeModal(modal);
attendi_speech_service_container.removeChild(attendi_speech_service);
}
);
// This event is fired when an error is thrown during the transcription API call.
// This allows you to handle these errors yourself.
attendi_speech_service.addEventListener("attendi-speech-service-error", (e) => {
// the name of the error can be accessed like so
console.log(e.detail.error); // e.g. "AttendiAuthenticationError"
// a more detailed error object can be accessed like so
console.log(e.detail.fullError);
});
`
#### Styling the component
The component's colors and fonts can be customized to match your own theme. Use the following CSS variables:
`css`
attendi-speech-service {
/ Color for main buttons /
--attendi-speech-service-button-color-primary: YOUR_COLOR;
/ Color for secondary buttons /
--attendi-speech-service-button-color-secondary: YOUR_COLOR;
--attendi-speech-service-button-text-color: YOUR_COLOR;
}
It may occur that the modal component is obscured by other elements of your application. This happens due to z-index issues.z-index
It is probably the case that either the on the modal is too low (though it has a sensible default value), or there is a "nested z-index" issue.
To mitigate this, either set a higher z-index on the modal HTML tag, or make sure the tag is not nested inside another tag. A simple way too ensure this is to place the tag just before the end of your document body.
On some devices using the Safari browser, it can take quite a long time before the recording actually starts. After some investigation, we found that on a MacBook Pro, it could take up to 3 (!) seconds for the recording to start, whereas it would only take about 200 ms on Chrome. It seems to be a bit better on iOS devices. A couple of things contribute to this bottleneck:
- The web API navigator.getUserMedia is used to allow the browser to access the device's microphone. Safari's implementation seems to be especially slow.audioWorkletNode.addModule
- is used to load a custom audio processing script. Here again, Safari's implementation is very slow.
These are web APIs that are out of our control, so there is not much we can currently do about it.
Sometimes the UI seems to freeze when starting the recording. This is because the getUserMedia somehow uses a lot of CPU in Safari, blocking the UI thread. It is not possible to move the call of the main thread, as getUserMedia is not available to web workers.
If you encounter any issues, don't hesitate to contact us at omar@attendi.nl.
This project is distributed under the Apache 2.0 License, see LICENSE.txt`, distributed with the package.