assemblyai 4.3.0 → 4.3.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [4.3.2] - 2024-03-08
+
+### Added
+
+- Add `audio_url` property to `TranscribeParams` in addition to the `audio` property. You can use one or the other. `audio_url` only accepts a URL string.
+- Add `TranscriptReadyNotification` type for the transcript webhook body.
+
+### Changed
+
+- Update codebase to use TSDoc
+- Update README.md with more samples
+
 ## [4.3.0] - 2024-02-15
 
 ### Added

package/README.md

@@ -16,9 +16,13 @@ The AssemblyAI JavaScript SDK provides an easy-to-use interface for interacting
 which supports async and real-time transcription, as well as the latest LeMUR models.
 It is written primarily for Node.js in TypeScript with all types exported, but also [compatible with other runtimes](./docs/compat.md).
 
-## Installation
+## Documentation
 
-You can install the AssemblyAI SDK by running:
+Visit the [AssemblyAI documentation](https://www.assemblyai.com/docs) for step-by-step instructions and a lot more details about our AI models and API.
+
+## Quickstart
+
+Install the AssemblyAI SDK using your preferred package manager:
 
 ```bash
 npm install assemblyai
@@ -36,11 +40,9 @@ pnpm add assemblyai
 bun add assemblyai
 ```
 
-# Usage
+Then, import the `assemblyai` module and create an AssemblyAI object with your API key:
 
-Import the AssemblyAI package and create an AssemblyAI object with your API key:
-
-```javascript
+```js
 import { AssemblyAI } from "assemblyai";
 
 const client = new AssemblyAI({
@@ -50,61 +52,94 @@ const client = new AssemblyAI({
 
 You can now use the `client` object to interact with the AssemblyAI API.
 
-## Create a transcript
+## Speech-To-Text
+
+### Transcribe audio and video files
+
+<details open>
+  <summary>Transcribe an audio file with a public URL</summary>
 
 When you create a transcript, you can either pass in a URL to an audio file or upload a file directly.
 
-```javascript
+```js
 // Transcribe file at remote URL
 let transcript = await client.transcripts.transcribe({
   audio: "https://storage.googleapis.com/aai-web-samples/espn-bears.m4a",
 });
+```
+
+> **Note**
+> You can also pass a local file path, a stream, or a buffer as the `audio` property.
+
+`transcribe` queues a transcription job and polls it until the `status` is `completed` or `error`.
+
+If you don't want to wait until the transcript is ready, you can use `submit`:
+
+```js
+let transcript = await client.transcripts.submit({
+  audio: "https://storage.googleapis.com/aai-web-samples/espn-bears.m4a",
+});
+```
+
+</details>
+
+<details>
+  <summary>Transcribe a local audio file</summary>
 
+When you create a transcript, you can either pass in a URL to an audio file or upload a file directly.
+
+```js
 // Upload a file via local path and transcribe
 let transcript = await client.transcripts.transcribe({
   audio: "./news.mp4",
 });
 ```
 
-> **Note**
-> You can also pass streams and buffers to the `audio` property.
+> **Note:**
+> You can also pass a file URL, a stream, or a buffer as the `audio` property.
 
 `transcribe` queues a transcription job and polls it until the `status` is `completed` or `error`.
-You can configure the polling interval and polling timeout using these options:
-
-```javascript
-let transcript = await client.transcripts.transcribe(
-  {
-    audio: "https://storage.googleapis.com/aai-web-samples/espn-bears.m4a",
-  },
-  {
-    // How frequently the transcript is polled in ms. Defaults to 3000.
-    pollingInterval: 1000,
-    // How long to wait in ms until the "Polling timeout" error is thrown. Defaults to infinite (-1).
-    pollingTimeout: 5000,
-  }
-);
-```
 
 If you don't want to wait until the transcript is ready, you can use `submit`:
 
-```javascript
+```js
 let transcript = await client.transcripts.submit({
+  audio: "./news.mp4",
+});
+```
+
+</details>
+
+<details>
+  <summary>Enable additional AI models</summary>
+
+You can extract even more insights from the audio by enabling any of our [AI models](https://www.assemblyai.com/docs/audio-intelligence) using _transcription options_.
+For example, here's how to enable [Speaker diarization](https://www.assemblyai.com/docs/speech-to-text/speaker-diarization) model to detect who said what.
+
+```js
+let transcript = await client.transcripts.transcribe({
   audio: "https://storage.googleapis.com/aai-web-samples/espn-bears.m4a",
+  speaker_labels: true,
 });
+for (let utterance of transcript.utterances) {
+  console.log(`Speaker ${utterance.speaker}: ${utterance.text}`);
+}
 ```
 
-## Get a transcript
+</details>
+
+<details>
+  <summary>Get a transcript</summary>
 
 This will return the transcript object in its current state. If the transcript is still processing, the `status` field will be `queued` or `processing`. Once the transcript is complete, the `status` field will be `completed`.
 
-```javascript
+```js
 const transcript = await client.transcripts.get(transcript.id);
 ```
 
-If you created a transcript using `submit`, you can still poll until the transcript `status` is `completed` or `error` using `waitUntilReady`:
+If you created a transcript using `.submit()`, you can still poll until the transcript `status` is `completed` or `error` using `.waitUntilReady()`:
 
-```javascript
+```js
 const transcript = await client.transcripts.waitUntilReady(transcript.id, {
   // How frequently the transcript is polled in ms. Defaults to 3000.
   pollingInterval: 1000,
@@ -113,11 +148,36 @@ const transcript = await client.transcripts.waitUntilReady(transcript.id, {
 });
 ```
 
-## List transcripts
+</details>
+<details>
+  <summary>Get sentences and paragraphs</summary>
+
+```js
+const sentences = await client.transcripts.sentences(transcript.id);
+const paragraphs = await client.transcripts.paragraphs(transcript.id);
+```
+
+</details>
+
+<details>
+  <summary>Get subtitles</summary>
+
+```js
+const charsPerCaption = 32;
+let srt = await client.transcripts.subtitles(transcript.id, "srt");
+srt = await client.transcripts.subtitles(transcript.id, "srt", charsPerCaption);
+
+let vtt = await client.transcripts.subtitles(transcript.id, "vtt");
+vtt = await client.transcripts.subtitles(transcript.id, "vtt", charsPerCaption);
+```
+
+</details>
+<details>
+  <summary>List transcripts</summary>
 
 This will return a page of transcripts you created.
 
-```javascript
+```js
 const page = await client.transcripts.list();
 ```
 
@@ -131,60 +191,18 @@ do {
 } while (nextPageUrl !== null);
 ```
 
-## Delete a transcript
-
-```javascript
-const res = await client.transcripts.delete(transcript.id);
-```
-
-## Use LeMUR
-
-Call [LeMUR endpoints](https://www.assemblyai.com/docs/API%20reference/lemur) to summarize, ask questions, generate action items, or run a custom task.
+</details>
 
-Custom Summary:
+<details>
+<summary>Delete a transcript</summary>
 
-```javascript
-const { response } = await client.lemur.summary({
-  transcript_ids: ["0d295578-8c75-421a-885a-2c487f188927"],
-  answer_format: "one sentence",
-  context: {
-    speakers: ["Alex", "Bob"],
-  },
-});
-```
-
-Question & Answer:
-
-```javascript
-const { response } = await client.lemur.questionAnswer({
-  transcript_ids: ["0d295578-8c75-421a-885a-2c487f188927"],
-  questions: [
-    {
-      question: "What are they discussing?",
-      answer_format: "text",
-    },
-  ],
-});
-```
-
-Action Items:
-
-```javascript
-const { response } = await client.lemur.actionItems({
-  transcript_ids: ["0d295578-8c75-421a-885a-2c487f188927"],
-});
+```js
+const res = await client.transcripts.delete(transcript.id);
 ```
 
-Custom Task:
-
-```javascript
-const { response } = await client.lemur.task({
-  transcript_ids: ["0d295578-8c75-421a-885a-2c487f188927"],
-  prompt: "Write a haiku about this conversation.",
-});
-```
+</details>
 
-## Transcribe in real-time
+### Transcribe in real-time
 
 Create the real-time transcriber.
 
@@ -255,11 +273,68 @@ Close the connection when you're finished.
 await rt.close();
 ```
 
-# Tests
+## Apply LLMs to your audio with LeMUR
 
-To run the test suite, first install the dependencies, then run `pnpm test`:
+Call [LeMUR endpoints](https://www.assemblyai.com/docs/api-reference/lemur) to apply LLMs to your transcript.
 
-```bash
-pnpm install
-pnpm test
+<details open>
+<summary>Prompt your audio with LeMUR</summary>
+
+```js
+const { response } = await client.lemur.task({
+  transcript_ids: ["0d295578-8c75-421a-885a-2c487f188927"],
+  prompt: "Write a haiku about this conversation.",
+});
 ```
+
+</details>
+
+<details>
+<summary>Summarize with LeMUR</summary>
+
+```js
+const { response } = await client.lemur.summary({
+  transcript_ids: ["0d295578-8c75-421a-885a-2c487f188927"],
+  answer_format: "one sentence",
+  context: {
+    speakers: ["Alex", "Bob"],
+  },
+});
+```
+
+</details>
+
+<details>
+<summary>Ask questions</summary>
+
+```js
+const { response } = await client.lemur.questionAnswer({
+  transcript_ids: ["0d295578-8c75-421a-885a-2c487f188927"],
+  questions: [
+    {
+      question: "What are they discussing?",
+      answer_format: "text",
+    },
+  ],
+});
+```
+
+</details>
+<details>
+<summary>Generate action items</summary>
+
+```js
+const { response } = await client.lemur.actionItems({
+  transcript_ids: ["0d295578-8c75-421a-885a-2c487f188927"],
+});
+```
+
+</details>
+<details>
+<summary>Delete LeMUR request</summary>
+
+```js
+const response = await client.lemur.purgeRequestData(lemurResponse.request_id);
+```
+
+</details>

package/dist/assemblyai.umd.js

@@ -54,14 +54,14 @@
     class BaseService {
         /**
          * Create a new service.
-         * @param params The parameters to use for the service.
+         * @param params - The parameters to use for the service.
          */
         constructor(params) {
             this.params = params;
         }
         fetch(input, init) {
-            var _a;
             return __awaiter(this, void 0, void 0, function* () {
+                var _a;
                 init = init !== null && init !== void 0 ? init : {};
                 init.headers = (_a = init.headers) !== null && _a !== void 0 ? _a : {};
                 init.headers = Object.assign({ Authorization: this.params.apiKey, "Content-Type": "application/json" }, init.headers);
@@ -122,7 +122,7 @@
         }
         /**
          * Delete the data for a previously submitted LeMUR request.
-         * @param id ID of the LeMUR request
+         * @param id - ID of the LeMUR request
          */
         purgeRequestData(id) {
             return this.fetchJson(`/lemur/v3/${id}`, {
@@ -205,8 +205,7 @@
             this.sampleRate = (_b = params.sampleRate) !== null && _b !== void 0 ? _b : 16000;
             this.wordBoost = params.wordBoost;
             this.encoding = params.encoding;
-            this.end_utterance_silence_threshold =
-                params.end_utterance_silence_threshold;
+            this.endUtteranceSilenceThreshold = params.endUtteranceSilenceThreshold;
             if ("token" in params && params.token)
                 this.token = params.token;
             if ("apiKey" in params && params.apiKey)
@@ -254,11 +253,11 @@
                 }
                 this.socket.binaryType = "arraybuffer";
                 this.socket.onopen = () => {
-                    if (this.end_utterance_silence_threshold === undefined ||
-                        this.end_utterance_silence_threshold === null) {
+                    if (this.endUtteranceSilenceThreshold === undefined ||
+                        this.endUtteranceSilenceThreshold === null) {
                         return;
                     }
-                    this.configureEndUtteranceSilenceThreshold(this.end_utterance_silence_threshold);
+                    this.configureEndUtteranceSilenceThreshold(this.endUtteranceSilenceThreshold);
                 };
                 this.socket.onclose = ({ code, reason }) => {
                     var _a, _b;
@@ -333,8 +332,8 @@
         }
         /**
          * Configure the threshold for how long to wait before ending an utterance. Default is 700ms.
-         * @param threshold The duration of the end utterance silence threshold in milliseconds
-         * @format integer
+         * @param threshold - The duration of the end utterance silence threshold in milliseconds.
+         * This value must be an integer between 0 and 20_000.
          */
         configureEndUtteranceSilenceThreshold(threshold) {
             this.send(`{"end_utterance_silence_threshold":${threshold}}`);
@@ -345,8 +344,8 @@
             }
             this.socket.send(data);
         }
-        close(waitForSessionTermination = true) {
-            return __awaiter(this, void 0, void 0, function* () {
+        close() {
+            return __awaiter(this, arguments, void 0, function* (waitForSessionTermination = true) {
                 if (this.socket) {
                     if (this.socket.readyState === WebSocket$1.OPEN) {
                         if (waitForSessionTermination) {
@@ -428,8 +427,8 @@
         }
         /**
          * Transcribe an audio file. This will create a transcript and wait until the transcript status is "completed" or "error".
-         * @param params The parameters to transcribe an audio file.
-         * @param options The options to transcribe an audio file.
+         * @param params - The parameters to transcribe an audio file.
+         * @param options - The options to transcribe an audio file.
          * @returns A promise that resolves to the transcript. The transcript status is "completed" or "error".
          */
         transcribe(params, options) {
@@ -440,45 +439,52 @@
         }
         /**
          * Submits a transcription job for an audio file. This will not wait until the transcript status is "completed" or "error".
-         * @param params The parameters to start the transcription of an audio file.
+         * @param params - The parameters to start the transcription of an audio file.
          * @returns A promise that resolves to the queued transcript.
          */
         submit(params) {
             return __awaiter(this, void 0, void 0, function* () {
-                const { audio } = params, createParams = __rest(params, ["audio"]);
                 let audioUrl;
-                if (typeof audio === "string") {
-                    const path = getPath(audio);
-                    if (path !== null) {
-                        // audio is local path, upload local file
-                        audioUrl = yield this.files.upload(path);
+                let transcriptParams = undefined;
+                if ("audio" in params) {
+                    const { audio } = params, audioTranscriptParams = __rest(params, ["audio"]);
+                    if (typeof audio === "string") {
+                        const path = getPath(audio);
+                        if (path !== null) {
+                            // audio is local path, upload local file
+                            audioUrl = yield this.files.upload(path);
+                        }
+                        else {
+                            // audio is not a local path, assume it's a URL
+                            audioUrl = audio;
+                        }
                     }
                     else {
-                        // audio is not a local path, assume it's a URL
-                        audioUrl = audio;
+                        // audio is of uploadable type
+                        audioUrl = yield this.files.upload(audio);
                     }
+                    transcriptParams = Object.assign(Object.assign({}, audioTranscriptParams), { audio_url: audioUrl });
                 }
                 else {
-                    // audio is of uploadable type
-                    audioUrl = yield this.files.upload(audio);
+                    transcriptParams = params;
                 }
                 const data = yield this.fetchJson("/v2/transcript", {
                     method: "POST",
-                    body: JSON.stringify(Object.assign(Object.assign({}, createParams), { audio_url: audioUrl })),
+                    body: JSON.stringify(transcriptParams),
                 });
                 return data;
             });
         }
         /**
          * Create a transcript.
-         * @param params The parameters to create a transcript.
-         * @param options The options used for creating the new transcript.
+         * @param params - The parameters to create a transcript.
+         * @param options - The options used for creating the new transcript.
          * @returns A promise that resolves to the transcript.
          * @deprecated Use `transcribe` instead to transcribe a audio file that includes polling, or `submit` to transcribe a audio file without polling.
          */
         create(params, options) {
-            var _a;
             return __awaiter(this, void 0, void 0, function* () {
+                var _a;
                 const path = getPath(params.audio_url);
                 if (path !== null) {
                     const uploadUrl = yield this.files.upload(path);
@@ -496,13 +502,13 @@
         }
         /**
          * Wait until the transcript ready, either the status is "completed" or "error".
-         * @param transcriptId The ID of the transcript.
-         * @param options The options to wait until the transcript is ready.
+         * @param transcriptId - The ID of the transcript.
+         * @param options - The options to wait until the transcript is ready.
          * @returns A promise that resolves to the transcript. The transcript status is "completed" or "error".
          */
         waitUntilReady(transcriptId, options) {
-            var _a, _b;
             return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
                 const pollingInterval = (_a = options === null || options === void 0 ? void 0 : options.pollingInterval) !== null && _a !== void 0 ? _a : 3000;
                 const pollingTimeout = (_b = options === null || options === void 0 ? void 0 : options.pollingTimeout) !== null && _b !== void 0 ? _b : -1;
                 const startTime = Date.now();
@@ -524,7 +530,7 @@
         }
         /**
          * Retrieve a transcript.
-         * @param id The identifier of the transcript.
+         * @param id - The identifier of the transcript.
          * @returns A promise that resolves to the transcript.
          */
         get(id) {
@@ -532,20 +538,20 @@
         }
         /**
          * Retrieves a page of transcript listings.
-         * @param parameters The parameters to filter the transcript list by, or the URL to retrieve the transcript list from.
+         * @param params - The parameters to filter the transcript list by, or the URL to retrieve the transcript list from.
          */
-        list(parameters) {
+        list(params) {
             return __awaiter(this, void 0, void 0, function* () {
                 let url = "/v2/transcript";
-                if (typeof parameters === "string") {
-                    url = parameters;
+                if (typeof params === "string") {
+                    url = params;
                 }
-                else if (parameters) {
-                    url = `${url}?${new URLSearchParams(Object.keys(parameters).map((key) => {
+                else if (params) {
+                    url = `${url}?${new URLSearchParams(Object.keys(params).map((key) => {
                     var _a;
                     return [
                         key,
-                        ((_a = parameters[key]) === null || _a === void 0 ? void 0 : _a.toString()) || "",
+                        ((_a = params[key]) === null || _a === void 0 ? void 0 : _a.toString()) || "",
                     ];
                 }))}`;
                 }
@@ -561,7 +567,7 @@
         }
         /**
          * Delete a transcript
-         * @param id The identifier of the transcript.
+         * @param id - The identifier of the transcript.
          * @returns A promise that resolves to the transcript.
          */
         delete(id) {
@@ -570,9 +576,9 @@
         /**
          * Search through the transcript for a specific set of keywords.
          * You can search for individual words, numbers, or phrases containing up to five words or numbers.
-         * @param id The identifier of the transcript.
-         * @param words Keywords to search for.
-         * @return A promise that resolves to the sentences.
+         * @param id - The identifier of the transcript.
+         * @param words - Keywords to search for.
+         * @returns A promise that resolves to the sentences.
          */
         wordSearch(id, words) {
             const params = new URLSearchParams({ words: words.join(",") });
@@ -580,29 +586,29 @@
         }
         /**
          * Retrieve all sentences of a transcript.
-         * @param id The identifier of the transcript.
-         * @return A promise that resolves to the sentences.
+         * @param id - The identifier of the transcript.
+         * @returns A promise that resolves to the sentences.
          */
         sentences(id) {
             return this.fetchJson(`/v2/transcript/${id}/sentences`);
         }
         /**
          * Retrieve all paragraphs of a transcript.
-         * @param id The identifier of the transcript.
-         * @return A promise that resolves to the paragraphs.
+         * @param id - The identifier of the transcript.
+         * @returns A promise that resolves to the paragraphs.
          */
         paragraphs(id) {
             return this.fetchJson(`/v2/transcript/${id}/paragraphs`);
         }
         /**
          * Retrieve subtitles of a transcript.
-         * @param id The identifier of the transcript.
-         * @param format The format of the subtitles.
-         * @param chars_per_caption The maximum number of characters per caption.
-         * @return A promise that resolves to the subtitles text.
+         * @param id - The identifier of the transcript.
+         * @param format - The format of the subtitles.
+         * @param chars_per_caption - The maximum number of characters per caption.
+         * @returns A promise that resolves to the subtitles text.
          */
-        subtitles(id, format = "srt", chars_per_caption) {
-            return __awaiter(this, void 0, void 0, function* () {
+        subtitles(id_1) {
+            return __awaiter(this, arguments, void 0, function* (id, format = "srt", chars_per_caption) {
                 let url = `/v2/transcript/${id}/${format}`;
                 if (chars_per_caption) {
                     const params = new URLSearchParams();
@@ -615,8 +621,8 @@
         }
         /**
          * Retrieve redactions of a transcript.
-         * @param id The identifier of the transcript.
-         * @return A promise that resolves to the subtitles text.
+         * @param id - The identifier of the transcript.
+         * @returns A promise that resolves to the subtitles text.
          */
         redactions(id) {
             return this.fetchJson(`/v2/transcript/${id}/redacted-audio`);
@@ -634,8 +640,8 @@
     class FileService extends BaseService {
         /**
          * Upload a local file to AssemblyAI.
-         * @param input The local file path to upload, or a stream or buffer of the file to upload.
-         * @return A promise that resolves to the uploaded file URL.
+         * @param input - The local file path to upload, or a stream or buffer of the file to upload.
+         * @returns A promise that resolves to the uploaded file URL.
          */
         upload(input) {
             return __awaiter(this, void 0, void 0, function* () {
@@ -661,7 +667,7 @@
     class AssemblyAI {
         /**
          * Create a new AssemblyAI client.
-         * @param params The parameters for the service, including the API key and base URL, if any.
+         * @param params - The parameters for the service, including the API key and base URL, if any.
          */
         constructor(params) {
             params.baseUrl = params.baseUrl || defaultBaseUrl;