README.md

metadata

title: TimeMarker for Cadayn
emoji: ⏱️
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.29.0
app_file: app.py
pinned: false
license: apache-2.0

TimeMarker ZeroGPU Space

Temporal video grounding via TimeMarker - #1 on LVBench for temporal localization.

Features

• Temporal Grounding: Find when specific events occur with timestamps
• Event Counting: Count occurrences with precise timestamps
• Sequential Description: Get timestamped narration of video content
• Long Video Support: Handles 2+ hour videos efficiently

When to Use TimeMarker vs Qwen2.5-VL

Query Type	Best Model	Example
"When does X happen?"	TimeMarker	"When does the goal occur?"
"How many times?"	TimeMarker	"How many goals are scored?"
"What is in this image?"	Qwen2.5-VL	"Describe the scene"
"Extract text"	Qwen2.5-VL	OCR tasks

API Usage

Temporal Grounding

import requests

response = requests.post(
    "https://YOUR-SPACE.hf.space/api/temporal_ground",
    json={
        "video_url": "https://example.com/video.mp4",
        "query": "when does the goal happen",
        "task": "ground",
        "num_frames": 32,
    }
)
print(response.json())

Event Counting

response = requests.post(
    "https://YOUR-SPACE.hf.space/api/temporal_ground",
    json={
        "video_url": "https://example.com/video.mp4",
        "query": "goals scored",
        "task": "count",
    }
)

Sequential Description

response = requests.post(
    "https://YOUR-SPACE.hf.space/api/temporal_ground",
    json={
        "video_url": "https://example.com/video.mp4",
        "task": "describe",
    }
)

Response Format

{
    "success": true,
    "result": "[TIME: 45.2s] Goal scored by player wearing red jersey...\n[TIME: 78.5s] Second goal...",
    "task": "ground",
    "model": "TimeMarker-LLM/TimeMarker-V2-7B"
}

Deployment

1. Create a new Space on HuggingFace with ZeroGPU hardware
2. Upload app.py and requirements.txt
3. Space auto-starts after dependency installation

Model

Uses TimeMarker-V2-7B with:

• Temporal separator tokens for precise timestamps
• Flash Attention 2 for efficiency
• bfloat16 precision
• Trained on temporal grounding datasets

Integration with EagleEye

Set environment variable:

TIMEMARKER_SPACE_URL=https://your-username-timemarker.hf.space

Smart Routing in EagleEye

TEMPORAL_KEYWORDS = {"when", "what time", "timestamp", "count", "how many"}

def select_vlm(query: str) -> str:
    if any(kw in query.lower() for kw in TEMPORAL_KEYWORDS):
        return "timemarker"  # Use this Space
    return "qwen25vl"  # Use Qwen Space

Limitations

• ZeroGPU has 180s timeout per function call
• Frame sampling may miss very brief events
• Cold start takes ~60-90s on first request
• Requires video URL (not local file upload via API)