Video Similarity Search: Find Matching Clips by Submitting a Video

from mixpeek import Mixpeek

client = Mixpeek(api_key="YOUR_API_KEY")

# 1. Create a namespace for your video catalog
client.namespaces.create(
    namespace_name="video-library",
    description="Video similarity search across the full archive",
)

# 2. Define a collection that segments + embeds video
#    The pipeline auto-splits each video into clips (by interval, scene
#    change, or shot boundary) and produces a multimodal embedding per clip.
client.collections.create(
    collection_name="video-clips",
    feature_extractors=[
        {
            "type": "video_segmentation",
            "strategy": "scene_detection",   # or "interval", "shot_boundary"
        },
        {"type": "video_embedding", "model": "multimodal"},
    ],
)

# 3. Upload videos and trigger automatic processing
client.buckets.upload(
    bucket_name="library-videos",
    files=["episode_001.mp4", "episode_002.mp4", "..."],
    auto_process=True,
)

# 4. Build a video similarity retriever
retriever = client.retrievers.create(
    retriever_name="video_similarity",
    inputs=[{"name": "query_clip", "type": "video"}],
    settings={
        "stages": [
            {"type": "feature_search", "method": "vector",
             "modalities": ["video"], "limit": 50},
            {"type": "rerank", "model": "cross-encoder-video", "limit": 10},
        ]
    },
)

# 5. Submit a query clip and get back matching segments with timestamps
results = client.retrievers.execute(
    retriever_id=retriever.retriever_id,
    inputs={"query_clip": "https://example.com/query-clip.mp4"},
)

# Each match returns the source video, start_time, end_time, score, and metadata
for doc in results.documents:
    print(f"{doc.metadata['source_video']}  "
          f"{doc.metadata['start_time']}s -> {doc.metadata['end_time']}s  "
          f"score={doc.score:.3f}")