ZIP File Format
Introduction
This document defines the expected format and structure of the ZIP file containing video frames for the SmartCare ZIP uploads. The server performs validation on the uploaded ZIP to ensure quality and consistency of input data.
Requirements Summary
- The file must be a valid ZIP archive.
- The ZIP must contain only JPG image files.
- Filenames must follow a strict timestamp-based naming convention.
- At least 20 seconds of footage must be included.
- The average frame rate must be ≥ 16 FPS.
Detailed Requirements
File Naming Format
Each file inside the ZIP must be named using the following convention:
17XXXXXXXXXXX.jpg
Where:
- 17XXXXXXXXXXX must be a Unix timestamp in milliseconds that precisely reflects the exact moment the frame was captured. The filename must begin with 17 followed by 11 digits.
- Example valid filenames:
- 1712345678253.jpg
- 1712349999754.jpg
Up to 5 incorrectly named files are tolerated; more will result in rejection.
Examples of invalid filenames
- frame1.jpg ❌
- 1712345678.jpg ❌
- 1712345678901.jpeg ❌
- image_1712345678.jpg ❌
- 17abcdefg.jpg ❌
Accurate timestamping is critical for ensuring correct temporal alignment during analysis.
Image File Requirements
- Each file must be a valid JPG image readable by standard image libraries.
- A random sample of 3 JPGs is tested for validity.
- Corrupt or unreadable files will cause the validation to fail.
Video Duration & FPS
The ZIP should contain sequential frames captured over time.
The validator extracts timestamps from the filenames and uses them to compute:
Minimum Duration
- Must span at least 20 seconds, based on the difference between the first and last frame timestamps.
Minimum FPS
- The average frame rate (calculated from timestamp intervals) must be ≥ 16 frames per second (FPS).
Troubleshooting
A ZIP upload will be rejected if one of the checks below fail (sorted):
- It is not a valid ZIP archive.
- It does not exist at the specified S3 key.
- More than 5 filenames do not match the required pattern.
- One or more sampled images are not valid JPGs.
- The footage duration is less than 20 seconds.
- The average FPS is less than 16.
Notes
- Timestamps are extracted by stripping the .jpg extension and converting the remaining string to an integer.
- Frame rate is calculated using the average difference between sorted timestamps.