A video recognition system that works like Shazam — but for video. It analyzes short snippets (2–5 seconds), breaks them into keyframes, and uses perceptual hashing to identify the exact or near-exact source, even if the clip has been edited or altered. This preserves the full context of the snippet and enables reliable tracking of original video content.

Key features:

• Upload full video snippets, not just images — automatic extraction of keyframes for context-aware matching.
• Accurate source identification via perceptual hashing tolerant to modifications.
• Optimized for quick, precise matching of short video fragments.
• Scalable microservices architecture built to handle heavy traffic without performance loss.

(back to top)

Turron is structured into 6 microservices, each with bounded responsibilities:

• Eureka Server: Manages service discovery using Netflix Eureka with @DiscoveryClient.

• Upload Service: Accepts short videos via REST API, stores them in MinIO, and sends processing tasks to Kafka.

• Frame Extraction Service: Extracts 5-10 keyframes from videos using FFmpeg, normalizes orientation for robustness, and forwards frames to Kafka for hashing.

...

• Hashing Service: Computes pHashes for keyframes and stores it in database.

• Search Service: Matches snippet videos to source videos using perceptual hash comparisons with sliding-window Hamming distance, storing results in database.

• API Gateway: Centralized REST API endpoint managing requests, authentication, and response aggregation.

(back to top)

Built With(back to top)

Set up Turron locally using Docker Compose for the dev environment or deploy to Kubernetes for production.

Ensure you have the following installed:

• Java 21
• Gradle
• Docker and Docker Compose
• kubectl (for prod environment)
• PostgreSQL, Kafka, MinIO (or use Docker Compose)

  java --version
  gradle --version
  docker --version

1. Clone the repository:

   git clone https://github.com/fl1s/turron.git

2. Navigate to the project directory:

   cd turron

3. Build all microservices with Gradle:

   cd /microservice-name
   ./gradlew clean build

4. Start the dev environment with Docker Compose:

   docker-compose up -d

5. Verify services are running:

   docker ps

6. (Will be added soon! In v1.2-v1.4) For prod, apply Kubernetes manifests:

   kubectl apply -f k8s/

(back to top)

POST {{api-gateway}}/api/v1/upload/snippet

Form Data:

Response:

{
  "snippetId": "...",
  "sourceUrl": "..."
}

POST {{api-gateway}}/api/v1/upload/source

Form Data:

Response:

{
  "sourceId": "...",
  "sourceUrl": "..."
}

GET {{api-gateway}}/api/v1/search/best-match/:snippetId

Path Parameter:

Response: The matched source MP4 video file

This project uses GitHub Actions.

The .github/workflows/build.yml workflow runs on every push and pull request to the main branch. It performs the following steps:

1. Checks out the repository
2. Sets up Java 21 using the Temurin distribution
3. Caches Gradle dependencies to speed up builds
4. Builds each service defined in the job matrix:
   • eureka-server
   • upload-service
   • extraction-service
   • hashing-service
   • search-service
   • api-gateway
5. Authenticates to GitHub Container Registry (GHCR)
6. Builds and pushes Docker images using a composite action located at .github/actions/docker-build-push

Each Docker image is tagged with:

• latest
• a short Git commit SHA
• a date-based tag in YYYYMMDD format

Our project includes out-of-the-box monitoring setup using Prometheus and Grafana.

• Each microservice exposes metrics via Spring Boot Actuator on the /actuator/prometheus endpoint.
• Prometheus scrapes these endpoints regularly to collect metrics.
• Grafana connects to Prometheus as a data source to visualize metrics on dashboards.

Prometheus config is located at:
monitoring/prometheus/prometheus.yml

• monitoring/prometheus/ — Prometheus config files
• monitoring/grafana/ — Grafana dashboards and config files

1. Start Prometheus using the config from monitoring/prometheus/prometheus.yml(it's already configured in docker-compose).
2. Start Grafana and add Prometheus as a data source (http://localhost:9090).
3. Create your dashboards in Grafana or import community dashboards for Spring Boot metrics.
4. Access your dashboards to monitor service health, performance, and custom metrics.

Contributions are welcome to enhance Turron! Follow these steps:

1. Fork the Project.
2. Create your Feature Branch:

   git checkout -b feature/fuzz-buzz-creature

3. Commit your Changes:

   git commit -m 'feat: add some fuzzBuzzCreatureFeature'

4. Push to the Branch:

   git push --set-upstream origin feature/fuzz-buzz-creature

5. Open a Pull Request.

Read our Contributing Guidelines for more details(I also do it later).

(back to top)

Distributed under the Apache 2.0 License. See LICENSE for more information.

(back to top)

fl1s - GitHub

Project Link: https://github.com/fl1s/turron

(back to top)