---
title: ZIP File Format
slug: smart-care/zip-file-format
icon: 🧑‍💻
docTags: 
createdAt: 2025-07-10T08:20:28.937Z
---

# 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:

:::BlockQuote
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**

- <font color="#F97316">**frame1**</font>.jpg ❌
- <font color="#F97316">**1712345678**</font>.jpg ❌
- 1712345678901.<font color="#F97316">**jpeg**</font> ❌
- <font color="#F97316">**image_1712345678**</font>.jpg ❌
- <font color="#F97316">**17abcdefg**</font>.jpg ❌

:::hint{type="warning"}
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**.