Guidance for Video Engagement Optimizer on AWS

Table of Contents

1. Overview
   • Cost
2. Prerequisites
   • Operating System
3. Deployment Steps
4. Deployment Validation
5. Running the Guidance
6. Next Steps
7. Cleanup
8. FAQ, known issues, additional considerations, and limitations
9. Notices
10. Authors

Overview

This Guidance helps YouTube creators, content marketers, and brand strategists understand and optimize their video channel engagement through AI-powered analysis. The system analyzes channel content to identify brand voice characteristics and compares top-performing versus bottom-performing videos, providing actionable insights to improve engagement.

Why did we build this Guidance?

Content creators often struggle to understand what makes their videos successful. This Guidance uses generative AI as a video engagement consultant to analyze video metadata (titles, descriptions, hashtags, posting schedules) across a channel's recent content. It identifies patterns that drive engagement and providing specific recommendations for improvement.

Architecture Overview

The architecture implements the following workflow:

1. User Input: User enters a YouTube channel name through the web interface
2. API Gateway: Routes requests to Lambda functions that invoke AI agents
3. Bedrock AgentCore: Hosts Strands Agent SDK-based AI agents that orchestrate the analysis
4. YouTube API Integration: Agents retrieve channel data, video metadata, and engagement metrics
5. DynamoDB Cache: Stores API responses to minimize YouTube API quota consumption
6. Streaming Response: Results are streamed back to the user interface via polling mechanism
7. Analysis Output: User receives comprehensive brand voice report or channel assessment with actionable recommendations

The system provides two analysis types:

• Brand Voice Analysis: Analyzes 15 recent videos to identify consistent brand characteristics
• Channel Assessment: Compares top 5 and bottom 5 performing videos from the last 6 months to identify success patterns

Cost

_You are responsible for the cost of the AWS services used while running this Guidance. As of November 2025, the cost for running this Guidance with the default settings in the US East (N. Virginia) Region is approximately $62.18 per month for processing 1,000 channel analyses._The primary cost driver is Amazon Bedrock LLM use. Costs scale linearly with usage as all services are consumption-based.

We recommend creating a Budget through AWS Cost Explorer to help manage costs. Prices are subject to change. For full details, refer to the pricing webpage for each AWS service used in this Guidance.

Sample Cost Table

The following table provides a sample cost breakdown for deploying this Guidance with the default parameters in the US East (N. Virginia) Region for one month, processing 1,000 channel analyses:

AWS Service	Dimensions	Cost [USD]
Amazon Bedrock (Claude Sonnet 4)	11,445 input tokens + 1,825 output tokens per analysis × 1,000 analyses	$61.70
Amazon Bedrock AgentCore Runtime	0.25 vCPU × 13.2 agent calls × 1,000 analyses	$0.23
AWS Lambda	1,000 API requests × 128MB memory × 1 second duration	$0.01
Amazon DynamoDB	1,000 analyses with caching (write/read operations)	$0.02
Amazon S3	Storage for agent artifacts and logs	$0.08
AWS Systems Manager Parameter Store	Secure storage for YouTube API key	$0.00
Amazon ECR	Container registry for agent images	$0.05
Amazon CloudWatch Logs	Log ingestion and storage	$0.01
Amazon API Gateway	1,000 REST API calls	$0.08
Total		$62.18
Cost per Analysis		$0.06

Note: This cost model assumes the current implementation without thumbnail analysis. Adding thumbnail analysis would increase costs by approximately 69% ($0.06 → $0.10 per analysis) due to additional image tokens processed by the foundation model.

Prerequisites

Operating System

These deployment instructions are optimized to work on macOS, Linux, and Windows.

Required Software:

• AWS CLI configured with appropriate credentials
• Git
• Node.js 18 or higher (for running the frontend locally)

Verification Commands:

# Verify AWS CLI is configured
aws sts get-caller-identity

# Verify Node.js version (for frontend)
node --version

Third-party tools

YouTube Data API v3 Key (Required)

You must obtain a YouTube Data API key from Google Cloud Console:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the YouTube Data API v3
4. Create credentials (API Key)
5. Copy the API key for use during deployment

AWS account requirements

• Service Quotas: Ensure your account has sufficient quotas for Lambda concurrent executions, DynamoDB tables, and Bedrock AgentCore agents.

Supported Regions

This Guidance supports deployment in AWS Regions where Amazon Bedrock AgentCore is available. As of November 2025, this includes:

• US East (N. Virginia) - us-east-1
• US East (Ohio) - us-east-2
• US West (Oregon) - us-west-2

The deployment scripts default to your AWS CLI configured region but can be overridden with the --region flag.

Deployment Steps

1. Clone the repository:

git clone https://github.com/aws-solutions-library-samples/guidance-for-video-content-optimization-assistant-on-aws.git
cd guidance-for-video-content-optimization-assistant-on-aws

2. Create S3 bucket for deployment packaging:

# Create unique bucket name using account ID and region
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
REGION=$(aws configure get region)
BUCKET_NAME="video-engagement-optimizer-deploy-${ACCOUNT_ID}-${REGION}"

# Create the bucket in the same region as deployment
aws s3 mb s3://${BUCKET_NAME} --region ${REGION}

3. Package and upload source code:

# Create zip file from backend source
cd source/backend
zip -r ../../backend-source.zip .
cd ../..

# Upload source code to S3 bucket
aws s3 cp backend-source.zip s3://${BUCKET_NAME}/backend-source.zip --region ${REGION}

4. Deploy the CloudFormation stacks:

Note: you must replace YOUR_YOUTUBE_API_KEY with a valid YouTube key

# Deploy networking stack (VPC, API Gateway, DynamoDB, Parameter Store)
aws cloudformation deploy \
  --template-file deployment/networking-stack.yaml \
  --stack-name video-engagement-optimizer-networking \
  --parameter-overrides YouTubeAPIKey=YOUR_YOUTUBE_API_KEY \
  --capabilities CAPABILITY_NAMED_IAM \
  --region ${REGION}

# Deploy core stack (ECR, CodeBuild, AgentCore Runtime, Lambda)
aws cloudformation deploy \
  --template-file deployment/core-stack.yaml \
  --stack-name video-engagement-optimizer-core \
  --parameter-overrides DeploymentBucket=${BUCKET_NAME} \
  --capabilities CAPABILITY_NAMED_IAM \
  --region ${REGION}

Note: Deployment takes approximately 15 minutes. CodeBuild will automatically build and deploy the agent container image from the uploaded source code.

3. Test the API to validate deployment

# Activate Python environment and install required Python package
python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
pip install requests

# Run the API test
python3 test_api.py @amazonwebservices

The test will automatically discover your API Gateway endpoint and API key, then perform a complete streaming analysis test.

Running the Guidance

Start the Web Interface

1. Navigate to the frontend directory:

cd frontend

2. Install Node.js dependencies (first time only):

npm install

3. Start the frontend application:

macOS/Linux/Windows:

python3 start_frontend.py --region us-east-1

The script will:

• Fetch the API Gateway configuration from your AWS account
• Create a secure configuration file
• Start the Next.js development server
• Open your browser to http://localhost:3000

Analyze a YouTube Channel

1. Enter Channel Name: In the web interface, enter a YouTube channel name (e.g., @amazonwebservices)

2. Select Analysis Type:

   • Brand Voice Analysis: Analyzes 15 most recent videos to identify brand characteristics
   • Channel Assessment: Compares top 5 vs bottom 5 performing videos from the last 6 months

3. View Results: The analysis streams in real-time, showing:

   • Channel overview and statistics
   • Brand voice characteristics or performance patterns
   • Actionable recommendations organized by timeline (immediate, short-term, long-term)
   • Specific examples from analyzed videos

Example Output

Brand Voice Analysis identifies:

• Consistent tone and messaging patterns
• Content themes and topics
• Posting schedule patterns
• Hashtag and keyword strategies

Channel Assessment provides:

• Comparison of successful vs unsuccessful video characteristics
• Specific recommendations for improvement
• Action plan with immediate, 30-day, and 90-day steps
• Data-driven insights based on actual performance metrics

Next Steps

Production Considerations

1. Enable API Authentication: Add Amazon Cognito to secure the API Gateway endpoints
2. Set Up Monitoring: Configure CloudWatch alarms for Lambda errors, DynamoDB throttling, and Bedrock quota limits
3. Implement Rate Limiting: Add API Gateway usage plans to prevent abuse
4. Enable CORS: Configure CORS settings in API Gateway for your production domain
5. Use Custom Domain: Set up a custom domain name with ACM certificate for the API Gateway

Cleanup

To remove all resources created by this Guidance:

# Delete the stacks in reverse order
aws cloudformation delete-stack \
  --stack-name video-engagement-optimizer-core \
  --region us-east-1

aws cloudformation delete-stack \
  --stack-name video-engagement-optimizer-networking \
  --region us-east-1

Wait for each stack deletion to complete before proceeding to the next:

# Monitor stack deletion status
aws cloudformation describe-stacks \
  --stack-name video-engagement-optimizer-core \
  --region us-east-1 \
  --query 'Stacks[0].StackStatus'

The cleanup will automatically:

• Delete Bedrock AgentCore agents
• Remove Lambda functions
• Delete API Gateway
• Remove DynamoDB tables (including cached data)
• Delete Parameter Store parameters
• Remove ECR repositories and images
• Delete IAM roles and policies
• Remove CloudWatch log groups

Note: Some VPC resources (VPC, subnets, security groups) may be retained to speed up stack deletion. These can be manually cleaned up later if needed.

FAQ, known issues, additional considerations, and limitations

Known Issues

Issue: YouTube API returns insufficient videos for analysis

• Resolution: The system automatically falls back from 6 months to 12 months of data if fewer than 8 videos are found. Channels with very infrequent posting may still have insufficient data.

Issue: Frontend shows "API configuration not found"

• Resolution: Ensure you run python3 start_frontend.py from the frontend/ directory, which automatically fetches the API Gateway URL from your AWS account

Additional Considerations

• Caching Strategy: The DynamoDB cache stores YouTube API responses for 7 days to minimize API calls and costs. Clear the cache if you need fresh data for recently updated channels.

• YouTube API usage: The YouTube API is free but provides a fixed number of API tokens per day. The system implements response caching for repeated analyses of the same channel to save on API token consumption.

• Regional Availability: This Guidance requires Amazon Bedrock AgentCore, which is only available in select regions. Verify service availability before deployment.

• Public API Endpoints: The default deployment creates API Gateway endpoints authenticated with an API key. Implement user-based authentication via Cognito, securing the web UI, before production use.

Limitations

• Video Platform Support: Currently supports YouTube only. Other platforms require additional API integrations.
• Analysis Depth: Analyzes metadata only (titles, descriptions, engagement statistics, metadata). Does not analyze video content, thumbnails, or audio.
• Language Support: Works best with English-language content. Other languages may produce less accurate results depending on the foundation model's training.
• Real-time Data: Analysis is based on cached data (7-day TTL). Very recent videos or engagement changes may not be reflected immediately.

Feedback

For any feedback, questions, or suggestions, please use the issues tab in this repository.

Notices

Customers are responsible for making their own independent assessment of the information in this Guidance. This Guidance: (a) is for informational purposes only, (b) represents AWS current product offerings and practices, which are subject to change without notice, and (c) does not create any commitments or assurances from AWS and its affiliates, suppliers or licensors. AWS products or services are provided "as is" without warranties, representations, or conditions of any kind, whether express or implied. AWS responsibilities and liabilities to its customers are controlled by AWS agreements, and this Guidance is not part of, nor does it modify, any agreement between AWS and its customers.

Authors

• David Rostcheck - AWS Solutions Architect