Stickers puzzle

تفاصيل العمل

# 🧩 Sticker Puzzle (AST)

> **Turn YouTube cartoon videos into tactile, interactive drag-and-drop puzzle games for kids!**

Sticker Puzzle transforms passive video consumption into an active, cognitive learning experience. When a YouTube link is shared to the app, the backend extracts video frames, removes backgrounds using AI cartoon segmentation, creates puzzle cutouts and stickers with cartoon borders, extracts looped audio clips, and delivers a multi-level drag-and-drop puzzle game on Android.

---

## 🌟 Features

- **🎬 YouTube to Puzzle in Seconds**: Share any YouTube cartoon video directly into the Android app via the native Android Share sheet (`ACTION_SEND`).

- **🤖 AI Cartoon Segmentation**: Uses `rembg` with the specialized `isnet-anime` model to extract crisp character stickers with custom white cartoon outlines.

- **✂️ OpenCV Contour Analysis & Puzzle Holes**: Automatically identifies distinct character contours, draws glowing cutout holes on the background, and cuts out individual puzzle pieces.

- **🎵 Endlessly Looping Audio**: Extracts high-energy 5-second audio loops from each video moment to accompany the puzzle level.

- **🎨 Interactive Custom Canvas UI (`PuzzleView`)**:

- **Squash & Stretch Physics**: Dynamic deformation and directional tilt during dragging.

- **Idle Jumping Animation**: Stickers bounce and squish playfully in the bottom arcade tray while waiting for touch.

- **Animated Cutout Hints**: Wiggling dashed outlines and particle sparkles guide the child to the target hole.

- **Celebration Sparkle Bursts**: Multi-colored particle explosions and audio cheer tones when pieces snap into place.

- **🕹️ Multi-Level Game Playlists**: Automatically extracts sequential puzzle scenes across the video timeline with animated level transitions.

- **🧠 Gradio AI Training Camp (`app.py`)**: Web-based training and categorization tool to scan videos, detect characters by HSV color and shape, and train a local character knowledge base.

- **📦 Release Pipeline (`release_build.sh`)**: Scripted release builds, APK signing, source snapshotting, and release diffing.

---

## 🏗️ Architecture

```

┌───────────────────────────────────────────────┐

│ YouTube Video Stream │

└──────────────────────┬────────────────────────┘

│

▼

┌───────────────────────────────────────────────────────────────────────────────────────────────┐

│ Python Backend (Termux / Linux) │

│ │

│ [yt-dlp] ──► Video Cache ──► [moviepy] ──► 5s Audio Loop (loop.mp3) / Video Clip │

│ ──► [OpenCV] ──► Timestamp Frame Capture │

│ ──► [rembg] ──► AI Anime Character Cutout │

│ ──► [OpenCV] ──► Dynamic Puzzle Holes + White Border Stickers │

│ ──► [FastAPI] ──► JSON Scene Manifest & Static Asset Server │

└─────────────────────────────────────────────┬─────────────────────────────────────────────────┘

│ HTTP (JSON + Assets)

▼

│ Android Client (Kotlin) │

│ │

│ • MainActivity : Catches YouTube URL share intent, pings API, loads game package. │

│ • GameActivity : Manages multi-level progression, timeline progress bar, audio playback. │

│ • PuzzleView : Custom canvas with Glide image loading, drag physics, particle effects. │

└───────────────────────────────────────────────────────────────────────────────────────────────┘

```

---

## 📁 Repository Structure

```

├── api.py # FastAPI server: scene & multi-level game generator

├── app.py # Gradio Web UI: video scanner & AI training camp

├── requirements.txt # Python dependencies

├── idea.mf # Original project concept & architecture design

├── assets/ # Generated puzzle scenes, video cache, and training data

│ ├── game_scenes/ # Scene folders (background.png, pieces, loop.mp3, scene.json)

│ ├── video_cache/ # Central cached YouTube video files

│ └── knowledge_base.json # Learned character feature database

└── android/ # Native Android Studio project (Kotlin)

├── build.gradle.kts # Top-level Gradle configuration

├── release_build.sh # Automated release builder and release diff tool

└── app/

├── build.gradle.kts # App-level build config (Kotlin 17, SDK 35, ViewBinding)

└── src/main/

├── AndroidManifest.xml

├── kotlin/com/stickerpuzzle/

│ ├── MainActivity.kt # Share handler & backend network coordinator

│ ├── GameActivity.kt # Multi-level game controller & audio manager

│ ├── PuzzleView.kt # Custom interactive Canvas game view & particle engine

│ └── SceneData.kt # Data models (SceneData, PuzzlePiece, GamePackage)

└── res/layout/

├── activity_main.xml # URL input & generation screen

└── activity_game.xml # Full-screen game layout with timeline & controls

```

---

## 🚀 Getting Started

### 1. Backend Setup (Termux or Linux)

Ensure Python 3.10+ and FFmpeg are installed:

```bash

# In Termux:

pkg update && pkg install python ffmpeg libjpeg-turbo libpng clang

# In Ubuntu / Debian:

sudo apt update && sudo apt install -y python3 python3-pip ffmpeg

```

Install the Python dependencies:

```bash

pip install -r requirements.txt

```

#### Run the FastAPI Game Server:

```bash

python api.py

```

*Server runs by default on `http://0.0.0.0:8000` (Swagger docs available at `http://localhost:8000/doc...`).*

#### Run the Gradio Training Camp (Optional):

```bash

python app.py

```

*Web interface available at `http://localhost:7860`.*

---

### 2. Android App Setup

#### Prerequisites:

- Android SDK (API 35, min SDK 26)

- Java / JDK 17

- Gradle 8+

#### Build Debug APK:

```bash

cd android

./gradlew assembleDebug

```

#### Build & Sign Release Package:

Set up `android/sticker-puzzle-release.credentials`:

```ini

RELEASE_KEYSTORE_PATH=/path/to/keystore.jks

RELEASE_KEY_ALIAS=your_alias

RELEASE_STORE_PASSWORD=your_keystore_password

RELEASE_KEY_PASSWORD=your_key_password

```

Run the automated release pipeline:

```bash

cd android

./release_build.sh 1 "Initial release"

```

The script will build the signed APK, verify the package, archive source snapshots in `releases/`, and copy the APK to `/sdcard/Download/sticker-puzzle-latest.apk`.

To compare two build releases:

```bash

./release_build.sh diff 1 2

```

---

## 📡 API Reference

### 1. `GET /generate_scene/`

Generates puzzle pieces, background, and audio for a specific video timestamp.

**Query Parameters:**

|---|---|---|---|

| `timestamp` | `int` | `10` | Video timestamp in seconds |

| `sensitivity` | `int` | `128` | Alpha threshold for character cutout |

**Response Example (`200 OK`):**

```json

{

"scene_id": "scene_a1b2c3d4",

"timestamp": 10,

"frame_width": 1280,

"frame_height": 720,

"audio_url": "/assets/game_scenes/scene_a1b2c3d4/loop.mp3",

"background_url": "/assets/game_scenes/scene_a1b2c3d4/background.png",

"pieces": [

{

"id": "piece_1",

"url": "/assets/game_scenes/scene_a1b2c3d4/piece_1.png",

"target_x": 420,

"target_y": 180,

"target_w": 250,

"target_h": 310,

"solved": false

}

]

}

```

### 2. `GET /generate_game/`

Generates a sequential multi-level puzzle package across the video timeline.

**Query Parameters:**

|---|---|---|---|

| `levels` | `int` | `5` | Number of puzzle levels to generate |

---

## 🎮 How to Play

1. Start `python api.py` on your host or Termux environment.

2. Launch the **Sticker Puzzle** Android app on your device or emulator.

3. In YouTube, open any cartoon, tap **Share**, and select **Sticker Puzzle** (or paste the URL directly into the app).

4. Tap **Make Puzzle!**.

5. Drag stickers from the bottom tray to match the glowing cutout holes on the background.

6. Complete each level to advance through the cartoon playlist!

---

## 📜 License

MIT License. Created for interactive learning and creative puzzle generation.

ملفات مرفقة

- MD
- readmeast.md
- (10.1KB)
- APK
- sticker-puzzle-debug.apk
- (6.54MB)

بطاقة العمل

اسم المستقل

حمود ح.

عدد الإعجابات

تاريخ الإضافة

20/08/2026

تاريخ الإنجاز

19/08/2026

المهارات

تفاصيل العمل

ملفات مرفقة

بطاقة العمل

روابط

تابع مستقل على

وسائل الدفع المتاحة