New serverless pattern - lambda-transcribe-sam-js

lambda-transcribe-sam-js/README.md

@@ -0,0 +1,80 @@
+# Amazon S3 to AWS Lambda to Amazon Transcribe using AWS SAM
+
+This pattern facilitates automatic audio transcription by using the Amazon Transcribe service through a serverless event-driven architecture. When audio files are uploaded to S3, they are automatically transcribed using Amazon Transcribe via a Lambda function invoked by S3 events.
+
+This pattern enables speech-to-text transcription use cases by providing a serverless event-based pipeline that can process audio files uploaded to S3. The pattern uses AWS Lambda to coordinate with the Amazon Transcribe service, making it easy to integrate transcription capabilities into your applications without the need to manage infrastructure or manually initiate transcription jobs.
+
+Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example.
+
+## Requirements
+
+* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
+* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured
+* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+* [AWS Serverless Application Model](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) (AWS SAM) installed
+
+## Deployment Instructions
+
+1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository:
+    ``` 
+    git clone https://github.com/aws-samples/serverless-patterns
+    ```
+1. Change directory to the pattern directory:
+    ```
+    cd lambda-transcribe-sam-js
+    ```
+1. From the command line, use AWS SAM to deploy the AWS resources for the pattern as specified in the template.yaml file:
+    ```
+    sam deploy --guided
+    ```
+1. During the prompts:
+    * Enter a stack name
+    * Enter the desired AWS Region
+    * Allow SAM CLI to create IAM roles with the required permissions.
+    * Allow TranscribeFunction to operate without authentication.
+    After running `sam deploy --guided` mode once and savings arguments to a configuration file (samconfig.toml), you can use `sam deploy` in future to use these defaults.
+
+2. Note the outputs from the SAM deployment process. These contain the resource names and/or ARNs which are used for testing.
+
+## How it works
+
+When an object is uploaded to S3:
+
+2. Lambda function starts a transcription job using Amazon Transcribe
+3. Amazon Transcribe processes the audio file and generates the transcription
+4. The transcription results are stored in the specified S3 bucket
+
+## Testing
+
+To test the deployed API endpoint:
+
+1. Upload an audio file to the created S3 bucket(Note: Bucket name would be {AWS::StackName}-audio-uploads):
+```
+aws s3 cp audio.mp3 s3://your-bucket-name/
+```
+2. Get the S3 URL of the uploaded audio file
+3. You can list all transcription jobs using:
+
+```bash
+aws transcribe list-transcription-jobs
+```
+4. You can check the transcription results in the S3 bucket once the job is complete:
+
+```bash
+aws transcribe get-transcription-job --transcription-job-name "job-name-from-response"
+```
+## Cleanup
+
+1. Delete the audio.mp3 file from the S3 bucket. This is because the bucket must be empty before it can be deleted.
+   ```bash
+    aws s3 rm "s3://your-bucket-name/audio.mp3"
+    ```
+2. Delete the stack
+    ```bash
+    sam delete
+    ```
+
+----
+Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: MIT-0

lambda-transcribe-sam-js/example-pattern.json

@@ -0,0 +1,62 @@
+{
+  "title": "Amazon S3 to AWS Lambda to Amazon Transcribe using AWS SAM",
+  "description": "This pattern creates a serverless pipeline that automatically triggers an Amazon Transcribe job when audio files are uploaded to an S3 bucket, using Lambda to orchestrate the transcription process.",
+  "language": "Javascript",
+  "level": "200",
+  "framework": "SAM",
+  "introBox": {
+    "headline": "How it works",
+    "text": [
+      "When audio files are uploaded to the S3 bucket, it automatically triggers a Lambda function that starts a transcription job using Amazon Transcribe. The Lambda function extracts information about the uploaded audio file and sends it to the Amazon Transcribe service, which processes the audio and generates a text transcription that is saved back to the specified S3 bucket in the "transcriptions" folder."
+    ]
+  },
+  "gitHub": {
+    "template": {
+      "repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/lambda-transcribe-sam-js",
+      "templateURL": "serverless-patterns/lambda-transcribe-sam-js",
+      "projectFolder": "lambda-transcribe-sam-js",
+      "templateFile": "template.yaml"
+    }
+  },
+  "resources": {
+    "bullets": [
+      {
+        "text": "Amazon S3",
+        "link": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html"
+      },
+      {
+        "text": "AWS Lambda",
+        "link": "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html"
+      },
+      {
+          "text": "Amazon Transcribe",
+          "link": "https://docs.aws.amazon.com/transcribe/latest/dg/what-is.html"
+        }
+    ]
+  },
+  "deploy": {
+    "text": [
+      "sam build",
+      "sam deploy --guided"
+    ]
+  },
+  "testing": {
+    "text": [
+      "See the GitHub repo for detailed testing instructions."
+    ]
+  },
+  "cleanup": {
+    "text": [
+      "sam delete"
+    ]
+  },
+  "authors": [
+    {
+      "name": "Achintya Veer Singh",
+      "image": "https://avatars.githubusercontent.com/u/55053737?v=4",
+      "bio": "Solutions Architect @ AWS",
+      "linkedin": "www.linkedin.com/in/achintya-veer-singh-493403193",
+      "twitter": "achintya_veer"
+    }
+  ]
+}

lambda-transcribe-sam-js/lambda-transcribe-sam-js.json

@@ -0,0 +1,101 @@
+{
+    "title": "Amazon S3 to AWS Lambda to Amazon Transcribe using AWS SAM",
+    "description": "This pattern creates a serverless pipeline that automatically invokes an Amazon Transcribe job when audio files are uploaded to an S3 bucket.",
+    "language": "Node.js",
+    "level": "200",
+    "framework": "SAM",
+    "introBox": {
+        "headline": "How it works",
+        "text": [
+            "When audio files are uploaded to the S3 bucket, an AWS Lambda function starts a transcription job using Amazon Transcribe. The Lambda function extracts information about the uploaded audio file and sends it to the Amazon Transcribe service, which processes the audio and generates a text transcription that is saved back to the specified S3 bucket."
+        ]
+    },
+    "gitHub": {
+        "template": {
+            "repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/lambda-transcribe-sam-js",
+            "templateURL": "serverless-patterns/lambda-transcribe-sam-js",
+            "projectFolder": "lambda-transcribe-sam-js",
+            "templateFile": "template.yaml"
+        }
+    },
+    "resources": {
+        "bullets": [
+            {
+                "text": "Amazon S3",
+                "link": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html"
+            },
+            {
+                "text": "AWS Lambda",
+                "link": "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html"
+            },
+            {
+                "text": "Amazon Transcribe",
+                "link": "https://docs.aws.amazon.com/transcribe/latest/dg/what-is.html"
+            }
+        ]
+    },
+    "deploy": {
+        "text": [
+            "sam build",
+            "sam deploy --guided"
+        ]
+    },
+    "testing": {
+        "text": [
+            "See the GitHub repo for detailed testing instructions."
+        ]
+    },
+    "cleanup": {
+        "text": [
+            "sam delete"
+        ]
+    },
+    "authors": [
+        {
+            "name": "Achintya Veer Singh",
+            "image": "https://avatars.githubusercontent.com/u/55053737?v=4",
+            "bio": "Solutions Architect @ AWS",
+            "linkedin": "www.linkedin.com/in/achintya-veer-singh-493403193",
+            "twitter": "achintya_veer"
+        }
+    ],
+    "patternArch": {
+        "icon1": {
+            "x": 10,
+            "y": 50,
+            "service": "s3",
+            "label": "Amazon S3"
+        },
+        "icon2": {
+            "x": 40,
+            "y": 50,
+            "service": "lambda",
+            "label": "AWS Lambda"
+        },
+        "icon3": {
+            "x": 65,
+            "y": 50,
+            "service": "transcribe",
+            "label": "Amazon Transcribe"
+        },
+        "icon4": {
+            "x": 90,
+            "y": 50,
+            "service": "s3",
+            "label": "Amazon S3"
+        },
+        "line1": {
+            "from": "icon1",
+            "to": "icon2",
+            "label": "Object Created"
+        },
+        "line2": {
+            "from": "icon2",
+            "to": "icon3"
+        },
+        "line3": {
+            "from": "icon3",
+            "to": "icon4"
+        }
+    }
+}

lambda-transcribe-sam-js/src/app.mjs

@@ -0,0 +1,76 @@
+import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+import { TranscribeClient, StartTranscriptionJobCommand } from '@aws-sdk/client-transcribe';
+
+const s3Client = new S3Client({ region: process.env.REGION });
+const transcribeClient = new TranscribeClient({ region: process.env.REGION });
+
+export const handler = async (event) => {
+  try {
+    // Get the S3 bucket and key from the event
+    const bucket = event.Records[0].s3.bucket.name;
+    const key = decodeURIComponent(event.Records[0].s3.object.key.replace(/\+/g, ' '));
+
+    console.log(`Processing file: s3://${bucket}/${key}`);
+
+    // Extract file name and extension for the transcription job
+    const fileName = key.split('/').pop();
+    const fileNameWithoutExt = fileName.substring(0, fileName.lastIndexOf('.')) || fileName;
+    const fileExt = fileName.substring(fileName.lastIndexOf('.') + 1).toLowerCase();
+
+    // Determine media format based on file extension
+    let mediaFormat;
+    switch (fileExt) {
+      case 'mp3':
+        mediaFormat = 'mp3';
+        break;
+      case 'wav':
+        mediaFormat = 'wav';
+        break;
+      case 'flac':
+        mediaFormat = 'flac';
+        break;
+      default:
+        throw new Error(`Unsupported file format: ${fileExt}`);
+    }
+
+    const transcriptionJobName = `${fileNameWithoutExt}-${Date.now()}`;
+
+    const mediaFileUri = `s3://${bucket}/${key}`;
+
+    const startTranscriptionParams = {
+      TranscriptionJobName: transcriptionJobName,
+      LanguageCode: 'en-US', 
+      MediaFormat: mediaFormat,
+      Media: {
+        MediaFileUri: mediaFileUri
+      },
+      OutputBucketName: bucket,
+      OutputKey: `transcriptions/${fileNameWithoutExt}.json`
+    };
+
+    const transcriptionCommand = new StartTranscriptionJobCommand(startTranscriptionParams);
+    const transcriptionResponse = await transcribeClient.send(transcriptionCommand);
+
+    console.log(`Started transcription job: ${transcriptionJobName}`);
+    console.log(`Transcription job response: ${JSON.stringify(transcriptionResponse)}`);
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify({
+        message: 'Transcription job started successfully',
+        jobName: transcriptionJobName,
+        jobStatus: transcriptionResponse.TranscriptionJob.TranscriptionJobStatus
+      })
+    };
+  } catch (error) {
+    console.error('Error processing the file:', error);
+
+    return {
+      statusCode: 500,
+      body: JSON.stringify({
+        message: 'Error starting transcription job',
+        error: error.message
+      })
+    };
+  }
+};