Merge pull request #37 from AssemblyAI/E07417BDFEA3614F5967B1520F8B2F61

Sync from internal repo (2024/03/08)

.eslintrc.json

@@ -5,8 +5,10 @@
   "parserOptions": {
     "project": ["./tsconfig.json"]
   },
-  "plugins": ["@typescript-eslint"],
-  "rules": {},
+  "plugins": ["@typescript-eslint", "eslint-plugin-tsdoc"],
+  "rules": {
+    "tsdoc/syntax": "warn"
+  },
   "ignorePatterns": ["/*.js", "/*.ts", "dist", "node_modules"],
   "overrides": [
     {
@@ -15,7 +17,6 @@
         "project": ["./tsconfig.test.json"]
       }
     },
-
     {
       "files": ["scripts/**/*"],
       "parserOptions": {

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.json

@@ -1,6 +1,6 @@
 {
   "name": "assemblyai",
-  "version": "4.3.1",
+  "version": "4.3.2",
   "description": "The AssemblyAI JavaScript SDK provides an easy-to-use interface for interacting with the AssemblyAI API, which supports async and real-time transcription, as well as the latest LeMUR models.",
   "engines": {
     "node": ">=18"
@@ -110,6 +110,7 @@
     "@typescript-eslint/eslint-plugin": "^6.7.5",
     "dotenv": "^16.3.1",
     "eslint": "^8.48.0",
+    "eslint-plugin-tsdoc": "^0.2.17",
     "jest": "^29.5.0",
     "jest-cli": "^29.5.0",
     "jest-fetch-mock": "^3.0.3",