video-ql 1.2.0

Searching through video data by asking the right questions

VideoQL

Searching through video data by asking the right questions.

Install it from PyPI

pip install video_ql

Usage

video_ql provides both a Python API and a CLI interface for video analysis and querying.

Python API

from video_ql import VideoQL
from video_ql.models import Query, QueryCondition, OrCondition, QueryConfig

# Define your queries
queries = [
    Query(
        query="Is the driver present in the forklift?",
        options=["yes", "no"]
    ),
    Query(
        query="Where is the forklift currently at?",
        options=["Truck", "Warehouse", "Charging"]
    ),
    Query(
        query="Is the forklift currently carrying cargo?",
        options=["yes", "no"]
    )
]

# Initialize VideoQL
video_ql = VideoQL(
    video_path="path/to/your/video.mp4",
    queries=queries,
    context="You are viewing the POV from inside a forklift"
)

# Analyze entire video
results = video_ql.analyze_video(display=True)

# Query specific conditions using our Pydantic models
query_config = QueryConfig(
    queries=[
        QueryCondition(
            query="Is the driver present in the forklift?",
            options=["yes"]
        )
    ]
)

# Query the video
matching_frames = video_ql.query_video(query_config)

Command Line Interface

1. Create a config file (config.yaml):

queries:
  - query: "Is the driver present in the forklift?"
    options: ["yes", "no"]
  - query: "Where is the forklift currently at?"
    options: ["Truck", "Warehouse", "Charging"]
  - query: "Is the forklift currently carrying cargo?"
    options: ["yes", "no"]
context: "You are viewing the POV from inside a forklift"
fps: 1.0
tile_frames: [3, 3]
frame_stride: 9
max_resolution: [640, 360]

2. Create a query file (query.yaml):

queries:
  - OR:
    - query: "Is the driver present in the forklift?"
      options: ["yes"]

3. Run the CLI:

video_ql --video path/to/video.mp4 \
         --config config.yaml \
         --query query.yaml \
         --output results/query_results \
         --display

You may also process a single frame using the following

python3 -m video_ql.single_frame \
         --image path/to/image.png \
         --config config.yaml \
         --output results/query_results.json \
         --display

Development

Read the CONTRIBUTING.md file.