Project GlyphMotion

Comprehensive Documentation

See How This Project Actually Works!

This project provides a web-based interface for real-time object tracking in videos. Users can upload a video file or provide a video URL, which is then processed by a local backend system. The system leverages the Ultralytics YOLOv8(m) model for object detection and tracking and integrates with GitHub Pages and Google Drive for storing and serving processed results.

Use Cases

Features

Project Structure

.
├── index.html                  # Main web interface (frontend)
├── admin.html                  # Admin login page
├── admin_tracker.html          # Admin dashboard for tracking processed videos and request origins
├── manifest.json               # PWA: Web App Manifest for installability
├── service-worker.js           # PWA: Service Worker for offline capabilities and caching
├── images/
    └── project-glyph-motion.ico  # Favicon for the website
    └── project-glyph-motion.png  # Project logo
    └── project-glyph-motion-192x192.png   # PWA icon (192x192)
    └── project-glyph-motion-512x512.png   # PWA icon (512x512)
    └── project-glyph-motion-maskable.png  # PWA maskable icon
    └── thumbnail_fallback.jpg  # Fallback thumbnail for videos
├── input/                      # Directory for uploaded video files (processed by the backend)
├── output/                     # Directory for processed video files (generated by the backend)
├── yolov8m.pt                  # Actual Pre-trained YOLOv8(m) model file (for object tracking) : Ultralytics YOLOv8(m) model file
├── tg.py (telegram.py)         # Backend orchestrator: handles web requests, triggers `ot.py`, integrates GitHub/Drive, and powers the Telegram bot.
├── ot.py (object_tracker.py)   # Core video processor: performs object tracking with YOLOv8(m).
├── gh.py (github.py)           # Manages GitHub commits and Google Drive integration.
├── client_secret.json          # Google Drive API credentials (for authenticated access)
├── config.yml                  # Configuration file for the backend (Paths and endpoints, etc.) [See the actual project config.yml for details]
├── admin_auth.py               # Handles secure admin authentication (stores bcrypt hashes)
├── admin_hash_gen.py           # Script to generate and update admin credentials directly in admin_auth.py
├── documentation.html          # This documentation file
├── requirements.txt            # Lists all Python dependencies
├── web_server_public.py        # Python script to run the Flask web server and Cloudflare Tunnel (Automation of the whole backend)
├── token.json                  # Google Drive API token file (for authenticated access)
├── videos.json                 # JSON file containing metadata for processed videos (links, titles, etc.)
├── tracking_data.json          # JSON file containing tracking data for processed videos (IP Address, Lat/Lon and object IDs, timestamps, etc.)
├── .gitignore                  # Specifies files and directories to ignore in Git
├── README.md                   # Project overview and setup instructions
└──LICENSE                      # Project license file

IMPORTANT WARNING: DO NOT MODIFY ANY CODE UNLESS EXPLICITLY INSTRUCTED. INCORRECT MODIFICATIONS CAN LEAD TO PROJECT FAILURE.

IMPORTANT NOTE ON FILE MANAGEMENT: Only index.html, videos.json, and the PWA files (manifest.json, service-worker.js) are strictly necessary to be uploaded to your GitHub repository and maintained there for the frontend. All other backend-related files (Python scripts, credentials, `tracking_data.json`, `config.yml`, etc.) are most recommended to be kept *only* on the local machine where the backend server is running. This ensures that no sensitive code or data is inadvertently pushed to GitHub, regardless of whether your repository is public or private.

How to Get a Free Custom Domain:

If you're a student, you can often get a free custom domain through the GitHub Education Pack. Popular registrars like Namecheap or Name.com offer free domains as part of this pack. You will typically need to verify your student status using your school/college ID card or academic email. Simply apply for the GitHub Education Pack, and once approved, you can claim your free domain.

Frontend Setup (Website)

The frontend consists of index.html, admin.html, and admin_tracker.html which use Tailwind CSS for styling and JavaScript for interactivity. It's recommended to set up the frontend first to understand the website's structure and then configure the backend.

Before proceeding with the website setup, it is crucial to read the "Security and Data Privacy (Admin Tracker)" section at the very end of this document to understand the implications of data collection and your responsibilities as a project owner.

1. Clone the Repository:

git clone <your-repository-url>
cd <your-repository-name>

2. Favicon Path:

Ensure the favicon path is correct in index.html, admin.html, and admin_tracker.html:

<link rel="icon" type="image/svg+xml" href="images/project-glyph-motion.ico">

Make sure the images folder and project-glyph-motion.ico file exist in your project's root directory relative to the HTML files.

3. Configure Frontend JavaScript Variables in index.html, admin.html, and admin_tracker.html:

Open these HTML files and locate the <script> section. You'll find important configuration variables. These URLs are examples; ensure they match your actual setup.

For index.html:


// IMPORTANT: This should now be your custom domain for GitHub Pages
const GITHUB_PAGES_REPO_URL = 'https://projectglyphmotion.studio/'; // Example: Replace with your GitHub Pages URL
const VIDEOS_JSON_PATH = 'videos.json';
const POLLING_INTERVAL_VIDEOS = 10000; // Poll videos.json every 10 seconds
const POLLING_INTERVAL_STATUS = 2000; // Poll live status every 2 seconds
const POLLING_INTERVAL_SERVER_HEALTH = 5000; // Poll server health every 5 seconds (new)

// IMPORTANT: This should be your custom domain for the backend tunnel
const NGROK_PUBLIC_URL = 'https://vot.onehorizon.me'; // Example: Replace with your Cloudflare Tunnel custom domain

const LOCAL_API_ENDPOINT = NGROK_PUBLIC_URL + '/process_web_video';
const LOCAL_STATUS_ENDPOINT = NGROK_PUBLIC_URL + '/status';
// ... other endpoints like LOCAL_DELETE_ENDPOINT, LOCAL_COMMIT_INFO_ENDPOINT, LOCAL_LOGOUT_ENDPOINT, etc.

// Configuration for how long central messages are displayed (in milliseconds)
const CENTRAL_MESSAGE_DISPLAY_DURATION_MS = 5000; // 5 seconds (configurable)

For admin.html and admin_tracker.html:


// IMPORTANT: This should be your custom domain for the backend tunnel
const NGROK_PUBLIC_URL = 'https://vot.onehorizon.me'; // Example: Replace with your Cloudflare Tunnel custom domain
const LOCAL_LOGIN_ENDPOINT = NGROK_PUBLIC_URL + '/login'; // For admin.html
const LOCAL_TRACKER_DATA_ENDPOINT = NGROK_PUBLIC_URL + '/admin_tracker_data'; // For admin_tracker.html
// ... other relevant endpoints

4. Progressive Web App (PWA) Integration:

Project GlyphMotion supports Progressive Web App (PWA) features, allowing users to install the application to their home screen on both desktop and mobile devices for an enhanced, app-like experience. This is achieved through manifest.json and service-worker.js.

No direct configuration is usually needed for manifest.json or service-worker.js unless you want to customize the PWA's appearance or caching strategy. Ensure these files are present in your project's root directory.

5. Open the Website (Local Preview):

You can simply open the index.html file in your web browser to see the frontend. The backend functionality will not work yet, but you can preview the UI.

Frontend Static Pages Serving (GitHub Pages DNS Configuration)

To ensure that the Project GlyphMotion frontend (e.g., https://projectglyphmotion.studio) loads reliably and independently of your local backend's tunnel status, we configure it to serve static pages directly from GitHub Pages. This involves setting up DNS records in Cloudflare to point your root domain to GitHub's servers. This guarantees your HTML, CSS, JavaScript, and videos.json files load consistently from GitHub's global content delivery network.

Steps to Configure GitHub Pages for Direct Domain Serving:

  1. Verify GitHub Pages Setup:

    Ensure your GitHub repository has GitHub Pages enabled. Go to your repository settings on GitHub, navigate to "Pages," and select the branch from which to publish (usually main or master). If you're using a custom domain, ensure it's specified there.

  2. Add Custom Domain (if applicable):

    If you wish to use a custom domain (e.g., projectglyphmotion.studio instead of your-username.github.io/your-repo/), add it in your GitHub repository's "Pages" settings under "Custom domain."

  3. Configure DNS Records in Cloudflare:

    Assuming you are using Cloudflare for DNS management (highly recommended for performance and security), you will need to add specific DNS records. These records instruct browsers to connect directly to GitHub's infrastructure without passing through the Cloudflare Tunnel. For our example domain projectglyphmotion.studio, we configured the following:

    For IPv4 Traffic (A Records):

    You will add multiple A records pointing to GitHub Pages' IPv4 addresses. For projectglyphmotion.studio, these were:

    • Type: A, Name: @ (or your domain/subdomain), IPv4 address: 185.199.108.153
    • Type: A, Name: @, IPv4 address: 185.199.109.153
    • Type: A, Name: @, IPv4 address: 185.199.110.153
    • Type: A, Name: @, IPv4 address: 185.199.111.153
    • Type: A, Name: @, IPv4 address: 192.30.252.153
    • Type: A, Name: @, IPv4 address: 192.30.252.154

    For IPv6 Traffic (AAAA Records):

    Similarly, add AAAA records for IPv6 support:

    • Type: AAAA, Name: @, IPv6 address: 2606:50c0:8000::153
    • Type: AAAA, Name: @, IPv6 address: 2606:50c0:8001::153
    • Type: AAAA, Name: @, IPv6 address: 2606:50c0:8002::153
    • Type: AAAA, Name: @, IPv6 address: 2606:50c0:8003::153

    IMPORTANT: For all these records (A and AAAA), ensure the "Proxy status" in Cloudflare is set to "DNS only" (grey cloud icon). This is critical to direct traffic straight to GitHub Pages instead of routing it through Cloudflare's proxy. If you see an orange cloud icon, click it to change it to grey. Note that these IP addresses are universal for GitHub Pages hosting and apply to any GitHub Pages project, whether hosted on a personal account or an organization account. They are not exclusive to a single project or user.

  4. DNS Propagation:

    After saving these DNS records, it may take some time for the changes to propagate across the internet. You can use tools like whatsmydns.net to check the propagation status for your domain and the specified IP addresses.

  5. Update GitHub Pages Custom Domain Settings:

    Once the DNS records are propagating, go back to your GitHub repository's "Pages" settings. Under "Custom domain," enter your root domain (e.g., projectglyphmotion.studio) and save. GitHub will verify the DNS records. If successful, your site will now be served directly from your custom domain.

This static serving setup ensures that your website's interface is always available to users, providing a consistent user experience regardless of whether your local backend is online. Any dynamic functionalities (like starting a new video analysis or accessing admin data) are handled by separate API calls to your backend subdomain (e.g., backend.projectglyphmotion.studio or vot.onehorizon.me), which still relies on the Cloudflare Tunnel. While these IP addresses are currently the official ones for GitHub Pages and are expected to be stable for a long time, it's always a good practice to periodically check GitHub's official documentation if you encounter unexpected loading issues, as these IPs can be updated by GitHub.

Backend Setup

The backend system consists of ot.py (object_tracker.py), tg.py (telegram.py), gh.py (github.py), admin_auth.py, and admin_hash_gen.py.

1. Install Python Dependencies:

You can install all necessary Python dependencies by running the following command:

pip install -r requirements.txt

The requirements.txt file is located in the project's root directory and lists all required libraries, including:

2. Configure tg.py (telegram.py):

Open tg.py and update the following configuration variables. These settings are fully configurable to suit your needs:

USE_GITHUB_PAGES = True  # Set to True to enable GitHub Pages integration (commits to repo, updates videos.json)

# Frame Restriction Configuration
FRAME_RESTRICTION_ENABLED = True # Set to True to enable frame count restriction
FRAME_RESTRICTION_VALUE = 7000 # Max allowed frames for video processing
FFPROBE_TIMEOUT_SECONDS = 30 # Timeout for ffprobe command in seconds

The Telegram bot functionality is pre-configured within tg.py. You just need to provide your bot's unique token:

TELEGRAM_BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN_HERE" # Replace with your bot token

You can obtain a bot token from BotFather on Telegram.

For admin functionality, ensure your JWT_SECRET_KEY is strong and random. Also, configure MASTER_ADMIN_USERNAMES if you want specific admins to have the ability to log out all other active sessions:

# JWT Secret Key (VERY IMPORTANT: Replace with a strong, random key in production!)
JWT_SECRET_KEY = 'YOUR_VERY_SECRET_JWT_KEY_HERE' # e.g., 'f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4'

# Master Admin Usernames (only these users can trigger global logout and other master actions)
# These users must also exist in ADMIN_CREDENTIALS in admin_auth.py
MASTER_ADMIN_USERNAMES = {"your_admin_username_1", "your_admin_username_2"} # Add more usernames to this set

You can generate a cryptographically secure key by opening a Python terminal and running:

import secrets
secrets.token_hex(32)

Copy the output and paste it as the value for your JWT_SECRET_KEY.

3. Configure admin_auth.py and admin_hash_gen.py:

The admin_auth.py file holds the bcrypt hashes of your admin credentials. DO NOT manually edit the hashes here unless you understand the bcrypt format. Instead, use the admin_hash_gen.py script to manage admin users and their passwords securely.

Run admin_hash_gen.py to add your initial admin users:

python admin_hash_gen.py

Follow the prompts to create or update admin usernames and passwords. This script will automatically update admin_auth.py with the new bcrypt hashes.

You can also configure session timeout for admin logins in admin_auth.py:

SESSION_TIMEOUT_ENABLED = True # Set to True or False
SESSION_DURATION_DAYS = 7 # Example: 7 days

4. Configure gh.py (github.py):

Open gh.py and update the following configuration variables. It is highly recommended to use environment variables for sensitive information like GITHUB_ACCESS_TOKEN in a production environment.

# GitHub API
_HARDCODED_GITHUB_ACCESS_TOKEN = "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN_HERE" # <--- IMPORTANT: Replace with your actual GitHub PAT
GITHUB_ACCESS_TOKEN = _HARDCODED_GITHUB_ACCESS_TOKEN if _HARDCODED_GITHUB_ACCESS_TOKEN != "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN_HERE" else os.getenv('GITHUB_ACCESS_TOKEN')

_HARDCODED_GITHUB_USERNAME = "YOUR_GITHUB_USERNAME_HERE" # <--- Replace with your GitHub username
GITHUB_USERNAME = _HARDCODED_GITHUB_USERNAME if _HARDCODED_GITHUB_USERNAME != "YOUR_GITHUB_USERNAME_HERE" else os.getenv('GITHUB_USERNAME')

_HARDCODED_GITHUB_REPO_NAME = "YOUR_GITHUB_REPO_NAME_HERE" # <--- Replace with your repository name
GITHUB_REPO_NAME = _HARDCODED_GITHUB_REPO_NAME if _HARDCODED_GITHUB_REPO_NAME != "YOUR_GITHUB_REPO_NAME_HERE" else os.getenv('GITHUB_REPO_NAME')

# Branch to commit to (usually 'main' or 'master' for GitHub Pages)
GITHUB_BRANCH = 'main'
# Path to the JSON file in your GitHub repository that stores video metadata
GITHUB_VIDEOS_JSON_PATH = 'videos.json'

# Google Drive API
# Ensure client_secret.json is in the same directory or provide its path
GOOGLE_DRIVE_CLIENT_SECRET_FILE = 'client_secret.json'
GOOGLE_DRIVE_TOKEN_FILE = 'token.json' # This file will be created after first authentication
# Name of the parent folder in Google Drive for processed videos (e.g., 'ObjectTrackerMaster/output')
GOOGLE_DRIVE_OUTPUT_FOLDER_NAME = 'ObjectTrackerMaster/output'

5. Cloudflare Tunnel Setup:

6. Run the Backend Orchestrator (tg.py / telegram.py):

Open a new terminal window. Navigate to your project folder and run:

python tg.py

(Use python3 for Linux/Ubuntu or python for Windows if python3 is not the default)

Usage

1. Ensure Backend System is Running:

Make sure your tg.py server is running locally AND the Cloudflare Tunnel is established. The "Server Status" indicator on the website should show "Online`.

To bring your backend system back online after stopping it, simply run these two commands (in separate terminal windows) from your project folder:

  1. Start Cloudflare Tunnel:
    sudo /usr/local/bin/cloudflared --config config.yml tunnel run project-glyph-motion-tunnel

    (Use python3 for Linux/Ubuntu or python for Windows if python3 is not the default)

  2. Start Backend Orchestrator:
    python tg.py

    (Use python3 for Linux/Ubuntu or python for Windows if python3 is not the default)

Once these two commands are running, your backend will be fully operational again, and the "Server Status" indicator on your website (index.html) will turn green, confirming that the backend is running and accessible.

2. Access the Project:

3. Provide Video Source (Web Interface):

4. Start Tracking (Web Interface):

Click the "Start Tracking" button.

5. Monitor Status:

The "Live Processing Status" area will update with messages from the backend system.

6. View Processed Videos:

Once processing is complete and tg.py (via gh.py) has updated the videos.json file and committed it to GitHub, the new video will appear in the "Processed Videos" gallery. You can click "Download / View Full" to see the tracked video.

7. Toggle Layout/View:

Use the "Enlarge View" / "Compact View" button to switch the main content box size, and the "Show 2 Videos per Row" / "Show 3 Videos per Row" button to adjust the video gallery layout. Your preferences will be saved locally.

How Video Processing Works

1. When you click "Start Tracking" on the web interface, the frontend (index.html) sends the video (either the file or URL) to your local tg.py server via the Cloudflare Tunnel public URL (e.g., https://vot.onehorizon.me).

2. tg.py (telegram.py) receives the request. It then calls ot.py (object_tracker.py) to perform the actual object tracking on the video.

3. After ot.py completes processing, tg.py orchestrates the post-processing steps by calling gh.py (github.py):

4. The frontend (index.html) continuously polls the videos.json file (hosted on GitHub Pages) to update the gallery with new processed videos.

How this project works? - A visual representation

This diagram provides a high-level overview of the Project GlyphMotion architecture, showing how different components interact to enable real-time object tracking and video management.

Frontend (Web & PWA) Backend (Local Server) External Services & Storage User Interface (index.html, admin.html) PWA Features (manifest.json, service-worker.js) Admin Tracker Dashboard (admin_tracker.html) Browser Local Storage (User Prefs, Admin Token) Backend Orchestrator (tg.py - Flask Server) Object Tracking Core (ot.py - YOLOv8(m)) GitHub & Google Drive Manager (gh.py) Admin Authentication (admin_auth.py, admin_hash_gen.py) Local Backend Data (tracking_data.json) Cloudflare Tunnel (cloudflared CLI, config.yml) Google Drive API (Uploads, Public Links) GitHub API (Commits, Read videos.json) Telegram Bot API (User Commands) GitHub Pages (Serves videos.json, Assets) HTTP/S Request (Video/URL) Admin Login/Tracker Data (Auth'd) Triggers Processing Provides Processed Video Admin File Ops (Delete) Stores Tracking Data Proxies HTTP/S Uploads Video Commits Metadata Receives Commands Serves videos.json, Assets Enhances Experience Caches Data Loads Preferences/Session User Interacts with UI Accesses PWA Stores Data Telegram Commands/Responses

Important Notes

Contributing

Feel free to fork this repository, submit pull requests, or open issues if you find bugs or have suggestions for improvements.

License

MIT License © 2025 Sayan Sarkar & Shitij Halder

Credits

Made with ❤️ by Sayan and Shitij

This project is based on the Ultralytics YOLOv8(m), an acclaimed real-time object detection and image segmentation model.

Security and Data Privacy (Admin Tracker)

Before you start exploring this project, you must know a few things regarding data privacy. The Admin Tracking Dashboard (admin_tracker.html) is a core part of this project, designed purely for security and operational monitoring purposes of the project owner. It allows the project owner to understand the origin of requests interacting with the backend for debugging, security auditing, and preventing misuse.

Please note: When you fork this project for your own use, you become the independent "user project owner." This means that the original project owners (Sayan and Shitij) will NOT have any access to any data you process or store on your fork. Your fork operates entirely independently, and the trust for responsible data handling rests with you. Your project's integrity will be built on the trust you potentially gain from your users.

WE, AS THE ORIGINAL PROJECT OWNERS, NEVER INTEND TO TRACK YOUR USERS' IP ADDRESSES OR THEIR LOCATIONS FOR PERSONAL OR BUSINESS MEANS, NOR WILL WE EVER DO SO. YOUR DATA IS SAFE WITH YOU.

Please be aware of the following:

Made with ❤️ by Sayan and Shitij
This project is based on the Ultralytics YOLOv8(m), an acclaimed real-time object detection and image segmentation model.