7.3 KiB
Video Analysis Specification
ADDED Requirements
Requirement: Video File Upload
The system SHALL provide an API endpoint for uploading video files. The system SHALL validate the uploaded file format and size. The system SHALL store the video file in the designated uploads directory. The system SHALL save video metadata to MongoDB.
Scenario: Successful Video Upload
- WHEN a user uploads a valid video file (supported formats: mp4, avi, mov, etc.)
- THEN the system SHALL save the file to the uploads directory
- AND the system SHALL create a video document in MongoDB with metadata (filename, file_path, upload_time, file_size, status)
- AND the system SHALL return a response with video_id and upload status
Scenario: Invalid File Format Upload
- WHEN a user uploads a file with unsupported format
- THEN the system SHALL reject the upload
- AND the system SHALL return an error message indicating the file format is not supported
Scenario: File Size Exceeds Limit
- WHEN a user uploads a video file exceeding the size limit
- THEN the system SHALL reject the upload
- AND the system SHALL return an error message indicating the file size limit
Requirement: Video Content Analysis
The system SHALL provide functionality to analyze video content using Alibaba Cloud DashScope MultiModal API. The system SHALL extract video frames at a configurable fps rate. The system SHALL call the DashScope API with the video file and analysis prompt. The system SHALL save the analysis results to MongoDB.
Scenario: Successful Video Analysis
- WHEN a user requests analysis for an uploaded video
- THEN the system SHALL read the video file from storage
- AND the system SHALL call DashScope MultiModalConversation API with the video file and fps parameter (default: 2)
- AND the system SHALL receive the analysis result from the API
- AND the system SHALL save the analysis result to MongoDB with video_id, analysis_type, content, fps, and created_at
- AND the system SHALL update the video status to "analyzed"
- AND the system SHALL return the analysis result to the user
Scenario: Analysis API Failure
- WHEN the DashScope API call fails (network error, API error, etc.)
- THEN the system SHALL handle the error gracefully
- AND the system SHALL update the video status to "failed"
- AND the system SHALL return an appropriate error message to the user
- AND the system SHALL log the error for debugging
Requirement: Video Summary Generation
The system SHALL provide functionality to generate a summary of video content. The system SHALL use the DashScope API to analyze the video and generate a summary based on a predefined prompt template. The system SHALL save the summary to MongoDB.
Scenario: Successful Summary Generation
- WHEN a user requests a summary for an analyzed video
- THEN the system SHALL call the DashScope API with the video file and summary prompt
- AND the system SHALL receive the summary text from the API
- AND the system SHALL save the summary to MongoDB with video_id, summary_text, and created_at
- AND the system SHALL return the summary to the user
Scenario: Summary for Unanalyzed Video
- WHEN a user requests a summary for a video that has not been analyzed
- THEN the system SHALL first perform video analysis
- AND the system SHALL then generate the summary
- AND the system SHALL return both analysis and summary results
Requirement: Video Comparison
The system SHALL provide functionality to compare content between multiple videos. The system SHALL extract content from each video. The system SHALL generate a comparison analysis highlighting similarities and differences. The system SHALL save the comparison result to MongoDB.
Scenario: Successful Video Comparison
- WHEN a user requests comparison between two or more videos
- THEN the system SHALL analyze each video if not already analyzed
- AND the system SHALL extract content from each video
- AND the system SHALL call the DashScope API with multiple video contents and comparison prompt
- AND the system SHALL generate a comparison result
- AND the system SHALL save the comparison to MongoDB with video_ids, comparison_result, and created_at
- AND the system SHALL return the comparison result to the user
Scenario: Comparison with Insufficient Videos
- WHEN a user requests comparison with less than two videos
- THEN the system SHALL reject the request
- AND the system SHALL return an error message indicating at least two videos are required
Requirement: Video List and Details
The system SHALL provide API endpoints to retrieve a list of uploaded videos and video details. The system SHALL return video metadata including upload time, file size, and analysis status.
Scenario: Retrieve Video List
- WHEN a user requests the list of videos
- THEN the system SHALL query MongoDB for all video documents
- AND the system SHALL return a list of videos with basic metadata (id, filename, upload_time, file_size, status)
Scenario: Retrieve Video Details
- WHEN a user requests details for a specific video
- THEN the system SHALL query MongoDB for the video document by video_id
- AND the system SHALL return detailed information including metadata, analysis results, and summary if available
Requirement: Frontend Video Management Interface
The system SHALL provide a static web interface for video management. The interface SHALL allow users to upload videos, view video list, trigger analysis, view summaries, and perform video comparisons.
Scenario: Upload Video via Frontend
- WHEN a user selects a video file and clicks upload in the frontend
- THEN the frontend SHALL send a POST request to /api/videos/upload with the video file
- AND the frontend SHALL display upload progress
- AND the frontend SHALL show success message and update the video list upon completion
Scenario: View Video Summary
- WHEN a user clicks to view summary for a video
- THEN the frontend SHALL send a GET request to /api/videos/{video_id}/summary
- AND the frontend SHALL display the summary text in a readable format
- AND if no summary exists, the frontend SHALL provide an option to generate one
Scenario: Compare Videos
- WHEN a user selects multiple videos and clicks compare
- THEN the frontend SHALL send a POST request to /api/videos/compare with video_ids
- AND the frontend SHALL display the comparison result in a structured format
- AND the frontend SHALL highlight similarities and differences
Requirement: Configuration Management
The system SHALL read configuration from config.yaml file. The system SHALL support environment variable overrides for sensitive configuration (API keys). The system SHALL validate configuration on startup.
Scenario: Load Configuration
- WHEN the application starts
- THEN the system SHALL read config.yaml file
- AND the system SHALL check for environment variables (DASHSCOPE_API_KEY, MONGODB_URI, etc.)
- AND the system SHALL override config values with environment variables if present
- AND the system SHALL validate required configuration items
- AND the system SHALL fail to start if required configuration is missing