AI-Powered Video Analysis
Relevant source files
The following files were used as context for generating this wiki page:The AI-Powered Video Analysis feature is a core component of the Adfluens application, designed to provide users with strategic insights into YouTube video performance. It leverages the Google Gemini AI model to analyze a video's content, metadata, and comments, generating a "Viral Analysis Report". This report breaks down the elements that contributed to a video's success, such as hooks and psychological triggers, and suggests new content ideas.
The system consists of two main functionalities: an initial, comprehensive analysis of a selected video and an interactive chat assistant that allows users to ask follow-up questions about the video's strategy. The entire feature is built on a full-stack architecture using React for the frontend and a tRPC-based Express server for the backend.
Sources: README.md:3, apps/web/src/features/ai/components/video-analyzer.component.tsx:28-31, apps/api/src/features/ai/ai.service.ts:13-16
High-Level Architecture
The feature follows a client-server model where the frontend React application communicates with a backend tRPC API. The backend service acts as a proxy and orchestrator for the Google Gemini AI API.
This diagram illustrates the end-to-end data flow for a video analysis request.
Frontend Implementation
The frontend logic is primarily encapsulated within the VideoAnalyzer React component. This component manages the state for the analysis process, displays the results, and provides the chat interface.
Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx
Component State and Logic
The VideoAnalyzer component uses React hooks to manage its internal state, including the analysis results, loading status, and chat history. Analysis results are cached in localStorage to prevent redundant API calls for the same video.
analysis: Stores theViralAnalysisResultobject received from the API.loading: A boolean to indicate when the initial analysis is in progress.error: Stores any error messages from the API call.chatMessages: An array ofChatMessageobjects for the interactive chat.chatLoading: A boolean to indicate when a chat response is pending.
The component's lifecycle for fetching and displaying an analysis is shown below.
Key Functions
handleAnalyze(force): Initiates the analysis by calling thetrpcClient.ai.analyze.mutateprocedure. It takes an optionalforceparameter to bypass the cache and re-fetch the analysis. Upon success, it stores the result in local storage and updates the component's state.handleSendMessage(e): Handles the submission of the chat form. It sends the current chat history and the new user message to thetrpcClient.ai.chat.mutateendpoint and appends the model's response to the chat history.
Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:68-85, 87-120
Integration
The VideoAnalyzer component is rendered within the VideoDetail component. It receives the video object and the fetched comments as props, which are essential inputs for the AI analysis.
Sources: apps/web/src/features/youtube/components/video-detail.component.tsx:180-182
Backend Implementation
The backend is responsible for defining the API endpoints, processing requests, and interacting with the Google Gemini API.
tRPC API Router (ai.router.ts)
The aiRouter defines two protected tRPC procedures, meaning they require user authentication.
analyze: A mutation that accepts video and comment data, calls theanalyzeVideoservice function, and returns the analysis result.chat: A mutation that accepts chat history, a new message, and video context, calls thechatAboutVideoservice function, and returns the AI's response.
The sequence diagram below shows the flow for an analyze request.
API Endpoint Inputs
ai.analyze
| Parameter | Type | Required | Description |
|---|---|---|---|
video | youtubeVideoSchema | Yes | The YouTube video object to analyze. |
comments | youtubeCommentSchema[] | No | An array of comments for sentiment context. Defaults to []. |
ai.chat
| Parameter | Type | Required | Description |
|---|---|---|---|
history | chatHistorySchema[] | No | The previous messages in the conversation. Defaults to []. |
message | string | Yes | The new message from the user. |
video | youtubeVideoSchema | Yes | The video context for the chat. |
analysis | viralAnalysisResultSchema | Yes | The initial analysis result for context. |
Sources: apps/api/src/features/ai/ai.router.ts:18-24, 35-41
AI Service (ai.service.ts)
This service contains the core business logic for communicating with the Google Gemini API.
-
analyzeVideo(video, comments):- Constructs a detailed prompt for the
gemini-2.5-flashmodel. The prompt instructs the AI to act as a video strategist and use Google Search grounding to analyze the video's content via its URL. - Includes video title, channel, description, and top comments as context.
- Specifies a strict JSON output format.
- Calls the Gemini API with the
googleSearchtool enabled. - Parses the JSON response and extracts grounding sources (URLs used by the AI) from the response metadata.
- Returns the structured
ViralAnalysisResult.
- Constructs a detailed prompt for the
-
chatAboutVideo(history, message, video, analysis):- Creates a chat session with the Gemini API.
- Provides a
systemInstructionto give the AI context about the video being discussed, including its title, summary, and viral reasons. - Sends the new user message to the ongoing chat session.
- Returns the AI's text response.
Sources: apps/api/src/features/ai/ai.service.ts:13-101, 111-143
Data Structures
The primary data structure for this feature is ViralAnalysisResult, which is shared between the frontend and backend via the @repo/types package.
ViralAnalysisResult
This diagram shows the structure of the ViralAnalysisResult type.
Fields
| Field | Type | Description |
|---|---|---|
summary | string | A brief summary of the video's content. |
hooks | string[] | A list of elements that grab the viewer's attention at the beginning. |
viralReasons | string[] | An analysis of the psychological or strategic reasons the video was shared. |
contentIdeas | string[] | A list of 3-5 actionable content ideas inspired by the video. |
sources | object[] | (Optional) A list of web sources the AI used for grounding, each with a title and uri. |
Sources: packages/types/src/ai/viral-analysis-result.type.ts:4-15, apps/api/src/features/ai/ai.service.ts:83-97
Summary
The AI-Powered Video Analysis feature provides a powerful, integrated experience for content creators. By combining a user-friendly React frontend with a robust tRPC backend that orchestrates calls to the Google Gemini API, it transforms raw video data into actionable strategic insights. The system is designed for efficiency, with features like local storage caching on the client and the use of Google Search grounding on the backend to ensure high-quality, context-aware analysis.