121 lines
7.3 KiB
Markdown
121 lines
7.3 KiB
Markdown
# 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
|
|
|