Forem: Boluwaji Akinsefunmi

Finding the Sequence of Strings Appeared on the Screen

Boluwaji Akinsefunmi — Wed, 18 Feb 2026 06:40:24 +0000

Problem Summary

The problem requires us to find all the strings that appear on the screen as Alice types a target string. Alice uses a special keyboard with two keys: one to append an 'a' and another to change the last character to its next alphabet letter. Our task is to return a list of all strings from the empty string to the target string with minimal keystrokes.

Intuition

Alice can build the target string by combining two operations: appending 'a' and modifying the last character. This means for each character in the target, she could either add an 'a' or modify the last character repeatedly until it matches the target’s character.

Step by Step Approach

Initialization: Start with an empty string and an empty list to store the sequences.
Build Strings: For each character in the target:
- Add an 'a' to the current string and save it.
- If the last character is not the target character, use key 2 to change the last character to its next counterpart and save this new string.
Repeat until you've processed all characters in the target.
Return the list of strings.

Here’s how the algorithm can be translated into JavaScript:

Complexity Analysis

Time Complexity: O(n^2), where n is the length of the target string, since for each character update, we may generate a number of intermediate strings.
Space Complexity: O(n) for the list of strings generated.

Final Code

function findSequence(target) {
    const result = [];
    let current = '';

    for (let i = 0; i < target.length; i++) {
        // Add the necessary number of 'a's
        while (current.length < i + 1) {
            current += 'a';
            result.push(current);
        }
        // Change previous character to the target character
        while (current[current.length - 1] !== target[i]) {
            current = current.slice(0, -1) + String.fromCharCode(current.charCodeAt(current.length - 1) + 1);
            result.push(current);
        }
    }
    return result;
}

Edge Cases

Single Character Target: If target consists of just one character, it will only generate strings leading up to that character. For example, if the target is 'z', the output will be all letters up to 'z'.
All Same Characters: If the target consists of repeating characters like 'aaa', the function must only increment after reaching the maximum string length of 'aaa'.

Wrap Up

This method efficiently builds the string sequences through systematic key presses. By following this approach, we can handle varying lengths and characters of the input target string succinctly. Try running the provided code with different inputs to see how it performs in practice.

Build Your Own GitHub Profile Widgets from Scratch

Boluwaji Akinsefunmi — Mon, 09 Feb 2026 23:21:18 +0000

A complete guide to designing, building, and deploying custom SVG widgets for your GitHub profile README.

Why Build Your Own?

If you've spent any time customizing your GitHub profile, you've probably used widgets like github-readme-stats, github-profile-trophy, or github-readme-streak-stats. They work great, until they don't. The trophy widget went down. The streak stats hit rate limits. The stats card shows stale data.

The reality is that these are someone else's free Vercel deployments running on someone else's GitHub token. When they break, you're stuck.

Building your own widgets gives you full control over design, data, uptime, and updates. And it's far simpler than you might think. This tutorial walks you through the entire process, from understanding how these widgets actually work to deploying your own via GitHub Actions and eventually Vercel.

How GitHub Profile Widgets Work
The Tech Stack
Understanding SVGs for GitHub
Fetching Data from the GitHub API
Building Your First Widget Step by Step
Widget Ideas and Patterns
Styling and Design Principles
Deployment Option (GitHub Actions)
Advanced Techniques
Troubleshooting
Project Template

1. How GitHub Profile Widgets Work

Every widget you see on a GitHub profile README follows the same pattern:

Your README.md contains an <img> tag
    ↓
The src points to a URL (e.g., some-api.vercel.app/api/widget?username=you)
    ↓
That URL is a server that:
    1. Receives your username as a query parameter
    2. Calls the GitHub API to fetch your stats
    3. Generates an SVG image dynamically
    4. Returns it with Content-Type: image/svg+xml
    ↓
GitHub's Markdown renderer displays the SVG inline

That's it. There's no magic. The "widget" is just a dynamically generated image.

There are two deployment models:

Live API (Vercel/Cloudflare Workers): The SVG is generated on every request. Always fresh, but depends on external hosting and can hit rate limits.

GitHub Actions (pre-generated): A scheduled workflow runs your script, generates SVG files, commits them to your repo. The README references local files (./widgets/my-widget.svg). No external dependencies, always available, but only updates on schedule.

This tutorial covers both approaches.

2. The Tech Stack

You need surprisingly little:

Language: Python (for GitHub Actions) or Node.js/TypeScript (for Vercel). This tutorial uses Python, but the concepts translate directly.

Data Source: The GitHub REST API or GraphQL API. The REST API is simpler; GraphQL gives you contribution data that REST can't access.

Output Format: SVG (Scalable Vector Graphics). This is the only format that makes sense, it's text-based (easy to generate programmatically), scales perfectly at any size, supports styling, and GitHub renders it natively.

Deployment: GitHub Actions (Phase 1) or Vercel Serverless Functions (Phase 2).

Dependencies: Just requests for Python (to call the GitHub API). That's it. No SVG libraries needed.

3. Understanding SVGs for GitHub

SVG is an XML-based image format. If you can write HTML, you can write SVG. Here's a minimal example:

<svg xmlns="http://www.w3.org/2000/svg" width="400" height="200" viewBox="0 0 400 200">
  <rect width="400" height="200" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
  <text x="24" y="40" font-size="18" font-weight="600" fill="#1d1d1f">
    Hello, GitHub!
  </text>
  <text x="24" y="64" font-size="13" fill="#86868b">
    This is a custom widget.
  </text>
  <rect x="24" y="80" width="200" height="8" rx="4" fill="#f0f0f0"/>
  <rect x="24" y="80" width="140" height="8" rx="4" fill="#007aff"/>
</svg>

That gives you a card with a title, subtitle, and a progress bar. No libraries needed.

What GitHub Supports in SVGs

GitHub proxies all images through camo.githubusercontent.com, which means some SVG features are stripped or blocked for security. Here's what works and what doesn't:

Works:

Basic shapes: <rect>, <circle>, <line>, <path>, <polygon>
Text: <text>, <tspan>
Gradients: <linearGradient>, <radialGradient>
Filters: <filter>, <feDropShadow>, <feGaussianBlur> (with limits)
Clipping: <clipPath>
Groups: <g> with transforms
Inline styles and <style> blocks
Emoji in text elements (renders as text, not images)
@import url() for Google Fonts (works but may be slow to load)
Defs and reusable elements

Does NOT work:

<script> tags (stripped for security)
<foreignObject> (stripped)
External images via <image href="..."> (blocked by CSP)
CSS animations with @keyframes (stripped by camo proxy)
<animate> / SMIL animations (stripped by camo proxy)
Embedded base64 images (blocked)
Fetching external resources

The main limitation is no interactivity and no animations when viewed on GitHub. Your SVGs need to be static but visually compelling.

SVG Coordinate System

SVGs use a coordinate system where (0,0) is the top-left corner:

(0,0) ──────────────── (width, 0)
  │                        │
  │     Your canvas        │
  │                        │
(0, height) ─────── (width, height)

The viewBox attribute defines the internal coordinate system. If your viewBox is 0 0 800 300, you work with coordinates from 0-800 horizontally and 0-300 vertically, regardless of the actual rendered size.

Key SVG Elements You'll Use

<!-- Rectangle with rounded corners -->
<rect x="10" y="10" width="200" height="100" rx="8" fill="#fff" stroke="#eee" stroke-width="1"/>

<!-- Circle -->
<circle cx="50" cy="50" r="20" fill="#007aff"/>

<!-- Text -->
<text x="10" y="30" font-family="Arial" font-size="14" fill="#333">Hello</text>

<!-- Line -->
<line x1="0" y1="100" x2="400" y2="100" stroke="#eee" stroke-width="1"/>

<!-- Path (for complex shapes) -->
<path d="M 10 80 Q 50 10 90 80 T 170 80" stroke="#007aff" fill="none" stroke-width="2"/>

<!-- Linear gradient -->
<defs>
  <linearGradient id="grad1" x1="0" y1="0" x2="1" y2="0">
    <stop offset="0%" stop-color="#007aff"/>
    <stop offset="100%" stop-color="#5856d6"/>
  </linearGradient>
</defs>
<rect fill="url(#grad1)" ... />

4. Fetching Data from the GitHub API

REST API Basics

The GitHub REST API is the simplest way to get profile data. Here's how to fetch what you need:

import requests

GITHUB_TOKEN = "ghp_your_token_here"  # Optional but recommended
USERNAME = "your-username"

headers = {
    "Accept": "application/vnd.github.v3+json",
    "Authorization": f"token {GITHUB_TOKEN}"  # Remove this line if no token
}

# Get user profile
user = requests.get(
    f"https://api.github.com/users/{USERNAME}",
    headers=headers
).json()

# Get repositories (up to 100)
repos = requests.get(
    f"https://api.github.com/users/{USERNAME}/repos",
    headers=headers,
    params={"per_page": 100, "sort": "updated"}
).json()

# Get languages for a specific repo
languages = requests.get(
    f"https://api.github.com/repos/{USERNAME}/some-repo/languages",
    headers=headers
).json()
# Returns: {"Python": 45000, "JavaScript": 12000, ...} (bytes of code)

# Get recent public events (activity)
events = requests.get(
    f"https://api.github.com/users/{USERNAME}/events/public",
    headers=headers,
    params={"per_page": 100}
).json()

What Data Is Available

Endpoint	What You Get	Use For
`/users/{user}`	Profile info, follower/following counts, public repo count	Header stats
`/users/{user}/repos`	All repos with name, language, stars, size, dates	Skyline, skill tree
`/repos/{user}/{repo}/languages`	Language breakdown in bytes	Language charts
`/users/{user}/events/public`	Last 90 days of public activity	Activity widgets
`/search/commits`	Commit search results	Commit patterns

Rate Limits

Without a token: 60 requests/hour. With a token: 5,000 requests/hour. For GitHub Actions, the built-in GITHUB_TOKEN gives you 1,000 requests/hour, which is plenty.

If you're iterating over repos to get language data, that's one API call per repo. For 50 repos, that's 50 calls — well within limits.

GraphQL API (For Contribution Data)

The REST API doesn't expose your contribution graph data. For that, you need GraphQL:

query = """
query($username: String!) {
  user(login: $username) {
    contributionsCollection {
      totalCommitContributions
      totalPullRequestContributions
      totalIssueContributions
      contributionCalendar {
        totalContributions
        weeks {
          contributionDays {
            contributionCount
            date
            weekday
          }
        }
      }
    }
  }
}
"""

response = requests.post(
    "https://api.github.com/graphql",
    headers={"Authorization": f"Bearer {GITHUB_TOKEN}"},
    json={"query": query, "variables": {"username": USERNAME}}
)
data = response.json()["data"]["user"]["contributionsCollection"]

This gives you the actual green-squares contribution data this is something that most third-party widgets can't even access without a user token.

5. Building Your First Widget Step by Step

Let's build a "Language Bar" widget from scratch. It shows your top languages as a horizontal stacked bar with labels — similar to the language bar on a GitHub repo, but for your entire profile.

Step 1: Gather the Data

from collections import defaultdict

# Language color mapping
LANG_COLORS = {
    "JavaScript": "#F7DF1E", "TypeScript": "#3178C6",
    "Python": "#3776AB", "HTML": "#E34F26",
    "CSS": "#1572B6", "Java": "#ED8B00",
    "Go": "#00ADD8", "Rust": "#DEA584",
    "Ruby": "#CC342D", "PHP": "#777BB4",
    "Swift": "#F05138", "Kotlin": "#7F52FF",
    "Shell": "#89E051", "C++": "#00599C",
    "Vue": "#4FC08D", "Dart": "#0175C2",
}

def get_language_stats(username, headers):
    """Aggregate language bytes across all repos."""
    repos = requests.get(
        f"https://api.github.com/users/{username}/repos",
        headers=headers,
        params={"per_page": 100, "type": "owner"}
    ).json()

    totals = defaultdict(int)
    for repo in repos:
        if repo.get("fork"):
            continue  # Skip forks
        langs = requests.get(
            f"https://api.github.com/repos/{username}/{repo['name']}/languages",
            headers=headers
        ).json()
        for lang, bytes_count in langs.items():
            totals[lang] += bytes_count

    return dict(sorted(totals.items(), key=lambda x: x[1], reverse=True))

Step 2: Build the SVG Generator

Think of your SVG generator as a function that takes data and returns a string:

def generate_language_bar(languages, username):
    width = 600
    height = 160
    total = sum(languages.values())

    # Start the SVG
    svg = f'''<svg xmlns="http://www.w3.org/2000/svg"
         width="{width}" height="{height}"
         viewBox="0 0 {width} {height}">

  <!-- Card background -->
  <rect width="{width}" height="{height}" rx="12"
        fill="#ffffff" stroke="#e8e8ed" stroke-width="1"/>

  <!-- Title -->
  <text x="24" y="36" font-family="Arial, sans-serif"
        font-size="16" font-weight="600" fill="#1d1d1f">
    Languages
  </text>
  <text x="24" y="54" font-family="Arial, sans-serif"
        font-size="12" fill="#86868b">
    @{username} · across all repositories
  </text>
'''

    # Draw the stacked bar
    bar_x = 24
    bar_y = 72
    bar_width = width - 48
    bar_height = 12
    current_x = bar_x

    # Clip path for rounded corners
    svg += f'''  <clipPath id="barClip">
    <rect x="{bar_x}" y="{bar_y}" width="{bar_width}"
          height="{bar_height}" rx="6"/>
  </clipPath>
  <g clip-path="url(#barClip)">\n'''

    top_langs = list(languages.items())[:8]

    for lang, bytes_count in top_langs:
        segment_width = (bytes_count / total) * bar_width
        if segment_width < 1:
            continue
        color = LANG_COLORS.get(lang, "#86868b")
        svg += f'    <rect x="{current_x:.1f}" y="{bar_y}" '
        svg += f'width="{segment_width:.1f}" height="{bar_height}" '
        svg += f'fill="{color}"/>\n'
        current_x += segment_width

    svg += '  </g>\n'

    # Legend dots and labels
    legend_y = 108
    col = 0
    row = 0
    for lang, bytes_count in top_langs:
        pct = bytes_count / total * 100
        color = LANG_COLORS.get(lang, "#86868b")
        x = 24 + col * 180
        y = legend_y + row * 22

        svg += f'  <circle cx="{x + 5}" cy="{y}" r="4" fill="{color}"/>\n'
        svg += f'  <text x="{x + 14}" y="{y + 4}" font-family="Arial" '
        svg += f'font-size="11" fill="#424245">{lang} {pct:.1f}%</text>\n'

        col += 1
        if col >= 3:
            col = 0
            row += 1

    svg += '</svg>\n'
    return svg

Step 3: Save It

svg_content = generate_language_bar(languages, "your-username")

import os
os.makedirs("widgets", exist_ok=True)
with open("widgets/language-bar.svg", "w") as f:
    f.write(svg_content)

Step 4: Reference in Your README

<div align="center">
  <img src="./widgets/language-bar.svg" alt="Language Bar" width="100%" />
</div>

That's the entire process. Every widget you build follows these four steps: gather data → generate SVG string → save to file → reference in README.

6. Widget Ideas and Patterns

Here are widget patterns categorized by complexity.

Beginner

Profile Stats Card: Display followers, repos, stars, and commits in a clean card layout. Straightforward rectangles and text positioning.

Language Pie/Bar Chart: Show your language distribution. Use SVG <circle> with stroke-dasharray for a donut chart, or stacked <rect> for a bar.

Social Links Banner: A styled banner with your social media handles. Simple text and color work.

Intermediate

Contribution Heatmap: Recreate the GitHub contribution graph with custom colors and styling. Requires GraphQL API for contribution data. It's a grid of small <rect> elements with varying fill opacity.

Activity Timeline: A vertical timeline showing your recent commits, PRs, and issues. Use the Events API and draw lines with circle markers.

Repo Showcase Card: A card highlighting your top-starred repos with descriptions, languages, and star counts.

Advanced

Code DNA: Generate a unique visual fingerprint from your coding patterns. Use trigonometric functions to create a double helix where colors represent languages.

Repo Skyline: A city skyline visualization where each building is a repo. Height maps to codebase size, color to primary language.

Skill Tree: An RPG-style tech tree showing your frameworks and languages with XP bars calculated from actual usage data.

Code Weather: A weather forecast metaphor for your coding activity. Commit frequency maps to weather conditions.

7. Styling and Design Principles

Typography in SVGs

GitHub's camo proxy doesn't always load external fonts reliably. Use system font stacks:

<text font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI',
      Helvetica, Arial, sans-serif" font-size="14" fill="#1d1d1f">
  Your text here
</text>

If you want to use Google Fonts, import them in a <style> block inside <defs>:

<defs>
  <style>
    @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600&amp;display=swap');
  </style>
</defs>

This adds a network request. On GitHub, font loading can be unreliable, so always provide fallbacks.

Design Tips for Great-Looking Widgets

Consistency matters. Pick a color palette and stick to it across all your widgets. If you go with Apple's design language, use their colors everywhere: #1D1D1F for primary text, #86868B for secondary, #007AFF for accents.

Generous padding. Don't cram content to the edges. Leave at least 24-32px of padding inside your card. White space makes everything look more polished.

Rounded corners. Use rx="12" or rx="16" on your card backgrounds. Sharp corners look dated.

Subtle shadows. A single feDropShadow with low opacity adds depth without being heavy:

<filter id="shadow">
  <feDropShadow dx="0" dy="1" stdDeviation="3"
                flood-color="#000" flood-opacity="0.04"/>
</filter>
<rect filter="url(#shadow)" ... />

Text hierarchy. Use font-weight and size to create visual levels, not color variety. A good system: title at 18px/600 weight, subtitle at 13px/400, labels at 11px/500 uppercase, values at 14px/600.

Limit your palette. Two or three accent colors maximum per widget. Language colors already add variety, your UI chrome should stay neutral.

Color Palettes Worth Trying

Apple Minimal (Light):
Background #FFFFFF, Card #F5F5F7, Text #1D1D1F, Secondary #86868B, Accent #007AFF

GitHub Dark:
Background #0D1117, Card #161B22, Text #E6EDF3, Secondary #8B949E, Accent #58A6FF

Warm Neutral:
Background #FAF9F6, Card #FFFFFF, Text #2D2D2D, Secondary #999, Accent #E07A5F

8. Deployment Option (Using GitHub Actions)

This is the simplest approach. A GitHub Action runs your Python script on a schedule, generates SVG files, and commits them to your repo.

Project Structure

your-username/
├── .github/
│   └── workflows/
│       └── update-widgets.yml
├── scripts/
│   └── generate_widgets.py
├── widgets/                    (auto-generated — don't edit by hand)
│   ├── widget-1.svg
│   └── widget-2.svg
├── README.md
└── requirements.txt

The Workflow File

Create .github/workflows/update-widgets.yml:

name: Update Profile Widgets

on:
  schedule:
    - cron: '0 6 * * *'         # Daily at 6 AM UTC
  workflow_dispatch:              # Manual trigger from Actions tab
  push:
    branches: [main]
    paths:
      - 'scripts/generate_widgets.py'

permissions:
  contents: write                 # Needed to push commits

jobs:
  update-widgets:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install requests

      - name: Generate widgets
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_USERNAME: ${{ github.repository_owner }}
          OUTPUT_DIR: widgets
        run: python scripts/generate_widgets.py

      - name: Commit and push
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add widgets/ README.md
          git diff --quiet && git diff --staged --quiet || (
            git commit -m "🎨 Update profile widgets [skip ci]"
            git push
          )

Key details:

The GITHUB_TOKEN is automatically provided by GitHub Actions — you don't need to create any secrets. It has read access to your public repos, which is all you need.

The [skip ci] in the commit message prevents the workflow from triggering itself in an infinite loop.

The git diff --quiet check ensures we only commit if files actually changed. This keeps your commit history clean.

workflow_dispatch lets you trigger the workflow manually from the Actions tab — useful during development.

Testing Locally

Before pushing, test your script locally:

# Set your token (optional for public repos, but increases rate limit)
export GITHUB_TOKEN="ghp_your_personal_access_token"
export GITHUB_USERNAME="your-username"
export OUTPUT_DIR="widgets"

# Run it
python scripts/generate_widgets.py

# Check the output
ls -la widgets/

# Open an SVG in your browser to preview
open widgets/my-widget.svg       # macOS
xdg-open widgets/my-widget.svg   # Linux

Debugging in Actions

If the workflow fails, check the Actions tab in your repo. Common issues:

Permission denied on push: Make sure permissions: contents: write is set in the workflow.
API rate limit: With GITHUB_TOKEN, you get 1,000 req/hr. If you have many repos, optimize by reducing API calls.
Empty diff: If widgets didn't change, the commit step is skipped silently. This is expected and correct.

9. Advanced Techniques

Generating Smooth Curves

For widgets like Code DNA that need organic shapes, use trigonometric functions:

import math

points = []
for i in range(100):
    t = i / 100
    x = start_x + t * total_width
    y = center_y + math.sin(t * math.pi * 4) * amplitude
    points.append((x, y))

# Convert to SVG path
path = f"M {points[0][0]:.1f} {points[0][1]:.1f}"
for x, y in points[1:]:
    path += f" L {x:.1f} {y:.1f}"

svg += f'<path d="{path}" stroke="#007aff" fill="none" stroke-width="2"/>'

For smoother curves, use quadratic or cubic Bézier path commands (Q or C) instead of line segments (L).

Creating Unique Visual Fingerprints

To make each user's widget visually distinct, hash their data and use the hash to seed visual parameters:

import hashlib
import json

data_string = json.dumps(sorted(user_languages.items()))
hash_hex = hashlib.md5(data_string.encode()).hexdigest()

# Extract deterministic parameters from hash
phase = int(hash_hex[:4], 16) / 65535 * math.pi * 2
frequency = 0.8 + (int(hash_hex[4:8], 16) / 65535) * 0.6
amplitude = 30 + (int(hash_hex[8:12], 16) / 65535) * 20

Every user gets a deterministically unique pattern that's consistent across regenerations but visually different from everyone else's.

SVG Patterns and Textures

Add visual interest with SVG patterns:

<defs>
  <pattern id="dots" width="10" height="10" patternUnits="userSpaceOnUse">
    <circle cx="5" cy="5" r="1" fill="#000" opacity="0.05"/>
  </pattern>
</defs>
<rect fill="url(#dots)" width="800" height="300"/>

Responsive Width

Make your widgets work at any display size using viewBox and percentage widths:

<svg viewBox="0 0 800 300" width="100%">
  <!-- Content designed for 800x300, scales to any width -->
</svg>

In your README:

<img src="./widgets/my-widget.svg" width="100%" />

Dark Mode Support

GitHub supports dark mode. You can create two versions of each widget and use GitHub's built-in theme-switching syntax:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./widgets/my-widget-dark.svg" />
  <source media="(prefers-color-scheme: light)" srcset="./widgets/my-widget-light.svg" />
  <img alt="Widget" src="./widgets/my-widget-light.svg" />
</picture>

This is a native GitHub Markdown feature that swaps images based on the viewer's system theme. For Vercel deployments, use a ?theme=dark query parameter instead.

10. Troubleshooting

Widget Not Updating on GitHub

GitHub aggressively caches images through its camo proxy. If you've updated your SVG but the old version still shows, try changing the image URL slightly (append ?v=2), or simply wait — the cache typically expires within a few hours.

SVG Looks Different on GitHub vs. Local Browser

GitHub's camo proxy sanitizes SVGs. If your widget renders differently on GitHub, check for unsupported features (animations, scripts, foreignObject), make sure fonts have proper fallbacks, and test by viewing the raw SVG file on GitHub rather than the rendered README.

GitHub API Returns 403

You've hit the rate limit. Add authentication (the Actions GITHUB_TOKEN increases limits to 1,000/hr), cache API responses during local development, and reduce the number of API calls by batching requests.

SVG Shows as a Broken Image

Common causes: invalid XML (unclosed tags, unescaped & — use & instead), a missing xmlns="http://www.w3.org/2000/svg" attribute on the root element, or the file is empty. Validate by opening the SVG directly in a browser.

Text Alignment Is Off

SVG text anchoring works differently than HTML:

<!-- Left-aligned (default): x is the LEFT edge -->
<text x="100" y="50">Left</text>

<!-- Center-aligned: x is the CENTER point -->
<text x="100" y="50" text-anchor="middle">Center</text>

<!-- Right-aligned: x is the RIGHT edge -->
<text x="100" y="50" text-anchor="end">Right</text>

The y coordinate is the text baseline (bottom of letters), not the top. So y="50" means the bottom of the text sits at y=50.

11. Project Template

Here's a minimal, copy-paste-ready template to get you started immediately:

#!/usr/bin/env python3
"""
Minimal GitHub Profile Widget Generator
Modify generate_widget() and you're done.
"""

import os
import requests
from collections import defaultdict

USERNAME = os.environ.get("GITHUB_USERNAME", "your-username")
TOKEN = os.environ.get("GITHUB_TOKEN", "")
OUTPUT = os.environ.get("OUTPUT_DIR", "widgets")

def github_get(endpoint, params=None):
    headers = {"Accept": "application/vnd.github.v3+json"}
    if TOKEN:
        headers["Authorization"] = f"token {TOKEN}"
    resp = requests.get(f"https://api.github.com{endpoint}",
                        headers=headers, params=params, timeout=30)
    return resp.json() if resp.status_code == 200 else {}

def fetch_data():
    user = github_get(f"/users/{USERNAME}")
    repos = github_get(f"/users/{USERNAME}/repos",
                       {"per_page": 100, "sort": "updated"})
    languages = defaultdict(int)
    for repo in (repos if isinstance(repos, list) else []):
        if not repo.get("fork"):
            langs = github_get(
                f"/repos/{USERNAME}/{repo['name']}/languages")
            for lang, count in langs.items():
                languages[lang] += count
    return {"user": user, "repos": repos, "languages": dict(languages)}

def generate_widget(data):
    width, height = 600, 120
    name = data["user"].get("name", USERNAME)
    repos = data["user"].get("public_repos", 0)
    followers = data["user"].get("followers", 0)

    return f'''<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}"
     viewBox="0 0 {width} {height}">
  <rect width="{width}" height="{height}" rx="12"
        fill="#fff" stroke="#e8e8ed" stroke-width="1"/>
  <text x="24" y="40" font-family="Arial, sans-serif"
        font-size="18" font-weight="600" fill="#1d1d1f">{name}</text>
  <text x="24" y="64" font-family="Arial, sans-serif"
        font-size="13" fill="#86868b">
    @{USERNAME} · {repos} repos · {followers} followers
  </text>
  <text x="24" y="96" font-family="Arial, sans-serif"
        font-size="12" fill="#aeaeb2">
    {len(data["languages"])} languages across all repositories
  </text>
</svg>
'''

if __name__ == "__main__":
    os.makedirs(OUTPUT, exist_ok=True)
    data = fetch_data()
    svg = generate_widget(data)
    path = os.path.join(OUTPUT, "my-widget.svg")
    with open(path, "w") as f:
        f.write(svg)
    print(f"Generated {path}")

Pair this with the workflow YAML from Section 8, push it to your profile repo, and you're live.

Building a Synchronised Internet Radio System with PHP, JS, and Zero Streaming Infrastructure

Boluwaji Akinsefunmi — Mon, 02 Feb 2026 10:35:41 +0000

Every traditional radio station has a simple promise: everyone tuning in hears the same thing at the same time. You turn on the radio at 2:05 PM, and you hear whatever programme is five minutes in, not the beginning, not a random track. You and every other listener are perfectly in sync.

I needed to build exactly that for a charity organisation's website, but online, without any live-streaming infrastructure. No Icecast. No Shoutcast. No WebRTC. No streaming servers at all.

Just PHP, JavaScript, MySQL, and a bit of maths.

In this article, I will walk you through the architecture, the sync algorithm that makes it work, and the pitfalls I encountered along the way.

The Problem

The charity already had a radio page on its website, essentially a list of uploaded MP3 files that visitors could click to play individually. News bulletins, member interviews, traditional music, and entertainment shows. Good content, but no structure. No "station" feel, just a glorified media player. A visitor would land on the page and see a list of 70+ files with no idea what to play.

What they wanted was a proper radio experience:

Admins upload media files and set schedules (e.g., "Morning News at 06:30, Member Spotlight at 09:00")
Certain tracks are designated as "loop/filler" media that play continuously when nothing is scheduled
When a listener opens the player, they hear whatever should be playing right now, mid-track if necessary
All listeners are synchronised, everyone hears the same content at the same position
It should work with the existing PHP stack

The constraint that changed everything: no live streaming. The charity doesn't have the infrastructure budget for a streaming server, and frankly doesn't need one. All their content is pre-recorded. The "live" element is purely the schedule of what plays when.

The Architecture

Here's the mental model:

┌─────────────────────────────────────────────────────┐
│                    ADMIN PANEL                       │
│  Upload media → Set schedules → Manage loop playlist │
└──────────────┬──────────────────────┬────────────────┘
               │                      │
               ▼                      ▼
        ┌─────────────┐      ┌──────────────┐
        │  /uploads/   │      │    MySQL      │
        │  (MP3/MP4)   │      │  (schedules,  │
        │              │      │   media meta,  │
        │              │      │   loop order)  │
        └──────┬───────┘      └──────┬────────┘
               │                      │
               │    ┌─────────────────┘
               │    │
               ▼    ▼
        ┌─────────────────┐
        │  /api/now-playing│ ◄── The brain
        │     .php         │
        └────────┬─────────┘
                 │
                 │  JSON: { media_url, offset, remaining, next }
                 │
        ┌────────▼─────────┐
        │   Player (JS)     │
        │                   │
        │  1. Fetch API     │
        │  2. Set src       │
        │  3. Seek to offset│
        │  4. Play          │
        │  5. Re-sync timer │
        └───────────────────┘

The entire system has four components:

Upload & metadata extraction:- Admin uploads media; the server detects duration via ffprobe (with a browser-based fallback)
Schedule management:- Admin says "play media #7 at 14:00 on Tuesday"
The now-playing API:- The brain. Given the current time, it determines what media should be playing and calculates the exact offset
The player:- Fetches the API, loads the media, seeks to the offset, plays, and periodically re-syncs

No WebSockets. No streaming protocol. Just an HTTP API and the HTML5 <audio> / <video> element.

The Database

Three tables. Deliberately simple.

CREATE TABLE radio_media (
    id INT AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    artist VARCHAR(255) DEFAULT '',
    filename VARCHAR(255) NOT NULL,
    filepath VARCHAR(500) NOT NULL,
    media_type ENUM('audio', 'video') NOT NULL DEFAULT 'audio',
    duration FLOAT NOT NULL DEFAULT 0,  -- seconds
    file_size BIGINT DEFAULT 0,
    is_loop TINYINT(1) NOT NULL DEFAULT 0,
    loop_position INT NOT NULL DEFAULT 0,
    cover_image VARCHAR(500) DEFAULT NULL,
    active TINYINT(1) NOT NULL DEFAULT 1,
    INDEX idx_loop (is_loop, loop_position)
);

CREATE TABLE radio_schedule (
    id INT AUTO_INCREMENT PRIMARY KEY,
    media_id INT NOT NULL,
    title VARCHAR(255) DEFAULT NULL,
    start_time DATETIME NOT NULL,
    end_time DATETIME NOT NULL,  -- auto-calculated: start_time + duration
    description TEXT,
    active TINYINT(1) NOT NULL DEFAULT 1,
    FOREIGN KEY (media_id) REFERENCES radio_media(id) ON DELETE CASCADE,
    INDEX idx_schedule_time (start_time, end_time)
);

CREATE TABLE radio_settings (
    setting_key VARCHAR(100) PRIMARY KEY,
    setting_value TEXT NOT NULL
);

A few design decisions worth noting:

end_time is stored, not computed. When an admin creates a schedule entry, the server calculates end_time = start_time + media.duration and stores it. This makes the "what's playing now?" query a simple range check rather than a join-and-compute.

is_loop and loop_position on radio_media convert any uploaded track into a filler playlist item. The loop_position determines the play order and is reorderable via drag-and-drop in the admin panel.

radio_settings stores the loop_epoch, a fixed reference timestamp that's critical to the loop sync algorithm. More on that next.

The Sync Algorithm

This is where the actual magic happens. There are two distinct sync problems to solve: scheduled content and loop content.

Scheduled Content Sync

This one is straightforward. If an admin schedules a 30-minute programme to start at 14:00, and a listener connects at 14:12:30, the offset is:

offset = current_time - schedule_start_time
offset = 14:12:30 - 14:00:00
offset = 750 seconds (12 minutes 30 seconds)

Every listener who calls the API at 14:12:30 gets offset: 750. They all seek to 12:30 in the audio file. Done.

The SQL query to find the active schedule:

$stmt = $db->prepare("
    SELECT s.*, m.*
    FROM radio_schedule s
    JOIN radio_media m ON s.media_id = m.id
    WHERE s.active = 1 AND m.active = 1
      AND s.start_time <= ?
      AND s.end_time > ?
    ORDER BY s.start_time DESC
    LIMIT 1
");
$stmt->execute([$now, $now]);

The ORDER BY start_time DESC with LIMIT 1 means that if two schedules overlap, the most recently started one wins. This is a deliberate choice; it lets admins override a running programme by scheduling something on top of it without deleting the original.

Loop Content Sync

The loop playlist is trickier. There's no "start time" for a loop — it plays continuously when nothing is scheduled. If the loop playlist is 2 hours of music, and it's been running "since forever", how do you tell two listeners connecting at slightly different moments to both play from the same position?

The answer: a fixed epoch and modular arithmetic.

// A fixed reference point that never changes once set
$epoch = strtotime(getSetting('loop_epoch', '2024-01-01 00:00:00'));

// Total duration of all loop tracks combined
$totalLoopDuration = array_sum(array_column($loopMedia, 'duration'));

// How far into the infinite loop cycle are we?
$elapsed = time() - $epoch;
$posInCycle = fmod($elapsed, $totalLoopDuration);

Think of it this way: imagine the loop playlist started playing at the epoch (1 January 2024 00:00:00) and has been playing non-stop ever since, repeating when it reaches the end. At any given moment, you can calculate exactly where in the playlist we would be:

Calculate total seconds since the epoch
Take the modulo of that against the total loop duration
Walk through the track list to find which track that position falls in
The remainder is the offset within that track

$accumulated = 0;
foreach ($loopMedia as $i => $track) {
    if ($accumulated + $track['duration'] > $posInCycle) {
        // This is the current track
        $currentTrack = $track;
        $trackOffset = $posInCycle - $accumulated;
        $trackRemaining = $track['duration'] - $trackOffset;
        break;
    }
    $accumulated += $track['duration'];
}

The beauty of this approach is that it's purely deterministic. Two servers, ten servers, a thousand listeners, no matter the traffic, they all compute the same result for the same timestamp. No shared state needed between requests. No "what was the last track we played?" tracking. Just maths.

Why a fixed epoch? Because fmod(elapsed, totalDuration) needs a stable reference point. If you used, say, "the time the loop started," you would need to persist and synchronise that state. The epoch is just a constant in the database; it can be any date in the past.

What if the loop playlist changes? If an admin adds or removes tracks, the total duration changes, which shifts everyone's position. This is acceptable; it's no different from a radio station changing its playlist. Listeners hear a brief jump. In practice, this rarely happens mid-playback.

Schedule-Loop Transitions

There's a subtle edge case: what happens when a loop track is playing and a scheduled programme is about to start? The player needs to switch at exactly the right moment.

The API handles this by checking if a scheduled item starts before the current loop track ends:

$nextSchedule = getNextScheduled($db, $nowDt);
$nextCheckIn = $trackRemaining;

if ($nextSchedule) {
    $scheduleStartsIn = strtotime($nextSchedule['start_time']) - $now;
    if ($scheduleStartsIn > 0 && $scheduleStartsIn < $trackRemaining) {
        // Tell the player to check back sooner
        $nextCheckIn = $scheduleStartsIn;
    }
}

The next_check_in value in the API response tells the player: "call me again in X seconds." Normally, this is the remaining duration of the current track. But if a schedule starts sooner, it returns the time until that schedule begins. The player re-fetches, gets the new scheduled media, and seamlessly transitions.

The Now-Playing API

The full response from /api/now-playing.php looks like this:

{
    "status": "scheduled",
    "server_time": 1738465200,
    "media": {
        "id": 42,
        "title": "Morning News Bulletin",
        "artist": "Ekiti Radio",
        "url": "/radio/uploads/media_abc123.mp3",
        "media_type": "audio",
        "duration": 1800,
        "cover_image": "/radio/uploads/covers/cover_xyz.jpg"
    },
    "offset": 750.23,
    "remaining": 1049.77,
    "schedule_title": "Ekiti Iroyin — Morning News",
    "next": {
        "type": "scheduled",
        "title": "Heritage Hour",
        "start_time": "2026-02-02 07:00:00"
    },
    "next_check_in": 1049.77
}

Key fields:

status: Either "scheduled" (a timetabled programme), "loop" (filler content), or "offline" (nothing to play)
offset: Where in the media file the player should seek to
remaining: Seconds until this media ends, used for progress display
next_check_in: When the player should call the API again

The server_time field is included so the player can detect clock drift between client and server, though in practice I found this unnecessary for most use cases.

Sync, Autoplay, and Latency Compensation on The Player

The player is a single HTML page with vanilla JavaScript. No frameworks. It uses the native <audio> and <video> elements with a custom UI on top.

The Core Playback Loop

async function fetchNowPlaying() {
    const requestStartTime = Date.now();

    const resp = await fetch(BASE + '/api/now-playing.php?_=' + Date.now());
    const data = await resp.json();
    const requestDuration = (Date.now() - requestStartTime) / 1000;

    const mediaChanged = !currentMedia || currentMedia.id !== data.media.id;

    if (mediaChanged) {
        loadMedia(data, requestDuration);
    } else {
        syncPosition(data.offset + requestDuration);
    }

    updateProgress(data.offset + requestDuration, data.media.duration);
    scheduleNextCheck(data.next_check_in);
}

Notice requestDuration. This is the first latency compensation mechanism.

Latency Compensation

Between the moment the server calculates the offset and the moment the player receives it, time has passed. On a fast connection, that's 50–200ms. On a slow mobile connection, it could be 1–2 seconds. If we don't account for this, listeners will consistently be slightly behind.

The fix is simple: measure the round-trip time and add half of it (or, more practically, the full request duration) to the offset:

const requestStartTime = Date.now();
const resp = await fetch(url);
const data = await resp.json();
const requestDuration = (Date.now() - requestStartTime) / 1000;

// The server said "you should be at 750 seconds" — but that was
// requestDuration ago. So we should actually be at:
activePlayer.currentTime = data.offset + requestDuration;

This is applied both when loading new media and when syncing position on existing media:

function loadMedia(data, requestDuration = 0) {
    currentMedia = data.media;
    // ... player setup ...

    activePlayer.src = data.media.url;
    activePlayer.currentTime = data.offset + requestDuration;
    activePlayer.volume = document.getElementById('volSlider').value;

    if (shouldAutoPlay) {
        activePlayer.play().then(() => {
            setPlayingState(true);
        }).catch(err => {
            console.warn('Autoplay failed:', err);
            setPlayingState(false);
        });
    }
}

Periodic Drift Correction

Even with accurate initial seeking, players drift over time. Buffering stalls, background tabs get throttled, devices sleep and wake, dozens of things can push a player out of sync.

The solution is a periodic re-sync. Every SYNC_INTERVAL seconds (default: 30), the player re-fetches the API and compares:

function syncPosition(expectedOffset) {
    if (!activePlayer || !isPlaying) return;
    const actualOffset = activePlayer.currentTime;
    const drift = Math.abs(actualOffset - expectedOffset);

    if (drift > MAX_DRIFT) {
        console.log(`Sync correction: drift ${drift.toFixed(1)}s`);
        activePlayer.currentTime = expectedOffset;
    }
}

// Re-sync periodically
setInterval(() => {
    if (isPlaying) fetchNowPlaying();
}, SYNC_INTERVAL * 1000);

The MAX_DRIFT threshold (default: 2 seconds) prevents constant micro-corrections. If the drift is under 2 seconds, it's imperceptible and not worth the audio glitch of seeking. If it's over 2 seconds, we force-correct.

The Autoplay Problem

Modern browsers aggressively block autoplay. You can't just call .play() on page load, the browser will reject it unless the user has interacted with the page first.

My solution uses a shouldAutoPlay flag that tracks user intent:

let shouldAutoPlay = false;

function play() {
    shouldAutoPlay = true; // User has expressed intent to listen

    if (!activePlayer || !activePlayer.src) {
        fetchNowPlaying(); // This will call loadMedia, which checks shouldAutoPlay
        return;
    }

    activePlayer.play().then(() => {
        setPlayingState(true);
    }).catch(() => {});
}

function pause() {
    shouldAutoPlay = false; // User wants silence
    if (activePlayer) activePlayer.pause();
    setPlayingState(false);
}

The key insight: once a user clicks play, shouldAutoPlay stays true forever (until they explicitly pause). This means when the player transitions between tracks, either because the current track ended or because fetchNowPlaying loaded a new one it automatically continues playing without requiring another click. The browser allows this because the original user gesture established an active audio context.

Seamless Track Transitions

When the current track ends (either a scheduled programme finishing or a loop track completing), the player needs to fetch the next thing to play. The ended event handles this:

audioEl.addEventListener('ended', fetchNowPlaying);
videoEl.addEventListener('ended', fetchNowPlaying);

But we don't just rely on ended. The API response includes next_check_in, which proactively schedules a re-fetch:

function scheduleNextCheck(seconds) {
    clearTimeout(checkTimer);
    checkTimer = setTimeout(fetchNowPlaying, Math.max(seconds, 2) * 1000);
}

This double approach of using both proactive scheduling and reactive ended listeners, means transitions happen cleanly even if there's slight timing mismatch between the calculated remaining time and the actual media duration.

Duration Detection

Here's a problem you won't find in most tutorials: to schedule a media file, you need its duration. To get the duration, you typically need ffprobe (from the ffmpeg suite) on the server. But not every shared hosting environment has ffmpeg installed.

The solution is a two-tier approach:

Tier 1: Server-side with ffprobe

function getMediaDuration(string $filepath): ?float {
    $cmd = 'ffprobe -v error -show_entries format=duration '
         . '-of csv=p=0 ' . escapeshellarg($filepath);
    $output = trim(shell_exec($cmd) ?? '');
    return is_numeric($output) ? (float) $output : null;
}

Tier 2: Browser-side JavaScript fallback

During upload, the admin panel creates a temporary media element to read the duration:

function handleFile(file) {
    const url = URL.createObjectURL(file);
    const el = file.type.startsWith('video') 
        ? document.createElement('video') 
        : document.createElement('audio');

    el.preload = 'metadata';
    el.onloadedmetadata = () => {
        detectedDuration = el.duration; // Got it!
        URL.revokeObjectURL(url);
    };
    el.src = url;
}

This detected duration is sent along with the upload form data. Additionally, the player itself can report duration back to the server for any media that still has duration = 0:

if (data.media.duration === 0 && activePlayer && activePlayer.duration) {
    fetch(BASE + '/api/media.php', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ id: data.media.id, duration: activePlayer.duration })
    });
}

This means even if both upload-time detections fail, the first person to play the media in a browser will "teach" the server its duration, and scheduling becomes available from that point.

Upload Handling

Uploads go through /api/upload.php. The important bits:

// Generate a unique filename to prevent file collisions
$uniqueName = uniqid('media_', true) . '.' . $ext;
$destPath = UPLOAD_DIR . '/' . $uniqueName;

move_uploaded_file($file['tmp_name'], $destPath);

// Try to get duration server-side
$duration = getMediaDuration($destPath);

// Fall back to JS-provided duration
if ($duration === null && !empty($_POST['duration'])) {
    $duration = (float) $_POST['duration'];
}

// Insert into database
$stmt = $db->prepare("
    INSERT INTO radio_media 
    (title, artist, description, filename, filepath, media_type, 
     mime_type, duration, file_size, is_loop, loop_position, cover_image)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
");

Files are stored with unique generated names (not the original filename) to avoid collisions and path traversal issues. The original title is stored in the database for display.

For large media files (think a 2-hour programme recording), you'll need to adjust PHP's upload limits:

; php.ini
upload_max_filesize = 500M
post_max_size = 500M
max_execution_time = 300

And if using Nginx:

client_max_body_size 500M;

Schedule Overlap Handling

What happens if an admin accidentally (or intentionally) creates overlapping schedules? Rather than blocking the overlap, the system allows it and applies a simple rule: the most recently started schedule wins. This logic behaves exactly like LIFO (Last-In, First-Out), but for a timeline rather than a stack.

// The ORDER BY DESC, LIMIT 1 means the latest-starting active 
// schedule takes priority
$stmt = $db->prepare("
    SELECT s.*, m.*
    FROM radio_schedule s
    JOIN radio_media m ON s.media_id = m.id
    WHERE s.active = 1 AND m.active = 1
      AND s.start_time <= ?
      AND s.end_time > ?
    ORDER BY s.start_time DESC
    LIMIT 1
");

The API does warn the admin about conflicts when creating a schedule:

$stmt = $db->prepare("
    SELECT s.id, s.start_time, s.end_time, m.title
    FROM radio_schedule s
    JOIN radio_media m ON s.media_id = m.id
    WHERE s.active = 1
      AND s.start_time < ?  -- new end
      AND s.end_time > ?    -- new start
");
$stmt->execute([$endTime, $startTime]);
$conflicts = $stmt->fetchAll();

if (!empty($conflicts)) {
    $response['warnings'] = ['This schedule overlaps with existing entries.'];
}

This is a conscious design choice. In a charity radio context, the admin might want to interrupt regular programming with an urgent announcement by simply scheduling on top. The last-start-wins rule makes this intuitive.

What About Video?

The system supports both audio and video out of the box. The player switches between an <audio> and <video> element depending on the media type:

function loadMedia(data, requestDuration = 0) {
    const isVideo = data.media.media_type === 'video';

    if (isVideo) {
        audioEl.pause();
        audioEl.src = '';
        activePlayer = videoEl;
        document.getElementById('videoWrap').classList.add('visible');
        document.getElementById('coverWrap').style.display = 'none';
    } else {
        videoEl.pause();
        videoEl.src = '';
        activePlayer = audioEl;
        document.getElementById('videoWrap').classList.remove('visible');
        document.getElementById('coverWrap').style.display = '';
    }

    activePlayer.src = data.media.url;
    activePlayer.currentTime = data.offset + requestDuration;
}

Video files are heavier, so seeking might take longer (the browser needs to download and buffer the video up to the seek point).

Performance Considerations

API Call Frequency

Each active listener calls /api/now-playing.php roughly:

Once on page load
Once every SYNC_INTERVAL seconds (default: 30)
Once per track transition

For 100 concurrent listeners with 30-second sync, that's about 200 requests per minute, plus transition spikes. This is very manageable for any standard PHP hosting.

The API query hits indexed columns (start_time, end_time, is_loop, active), so even with a large media library and schedule history, response times stay under 10ms.

Media File Delivery

The media files are served as standard static files by your web server (Apache/Nginx). The HTML5 media element handles range requests natively, which means:

Listeners only download from the seek point forward (not the entire file)
Nginx/Apache serve range requests efficiently without PHP involvement
No PHP process is tied up during media delivery

This is a crucial advantage over streaming-based solutions where every byte flows through your application layer.

Cache Busting

The API call includes a cache buster to prevent stale responses:

fetch(BASE + '/api/now-playing.php?_=' + Date.now())

You should also set appropriate cache headers server-side:

header('Cache-Control: no-cache, no-store, must-revalidate');

Limitations and Honest Trade-offs

This approach has genuine limitations compared to a proper streaming setup:

Seek latency on slow connections. When a listener connects, their browser needs to download from the seek point. On a slow connection, there might be a few seconds of buffering before audio starts. A streaming server would deliver the audio in real-time from the exact point.

File format matters. MP3 seeking depends on bitrate consistency. VBR (Variable Bit Rate) MP3s can have inaccurate seeks. CBR (Constant Bit Rate) or properly indexed files work best.

No sub-second sync precision. Listeners will typically be within 1–2 seconds of each other. For a radio station, this is perfectly acceptable. For something like a live concert simulcast, it wouldn't be.

No adaptive bitrate. A proper streaming server can adjust quality based on the listener's connection speed. Here, every listener gets the same file. If you upload a 320kbps MP3, listeners on slow connections might buffer.

The loop playlist shift problem. If you change the loop playlist while listeners are active (add/remove tracks), everyone's position jumps because the total duration changes. The workaround is to make playlist changes during scheduled content or off-peak hours.

For a charity radio station playing pre-recorded content, these trade-offs are entirely acceptable. You get a fully functional radio experience with zero infrastructure beyond a basic web server.

Embedding the Player

The player can be embedded anywhere on your existing website via an iframe:

<iframe 
    src="/radio/player.php" 
    width="500" 
    height="700" 
    frameborder="0"
    allow="autoplay"
></iframe>

Or you can use the API directly to build a custom mini-player:

async function initMiniRadio() {
    const resp = await fetch('/radio/api/now-playing.php');
    const data = await resp.json();

    if (data.status === 'offline') {
        document.getElementById('radio').textContent = 'Off Air';
        return;
    }

    const audio = document.getElementById('radio-audio');
    audio.src = data.media.url;
    audio.currentTime = data.offset;

    document.getElementById('track-name').textContent = data.media.title;
}

Because the sync logic lives entirely in the API, any player that can make an HTTP request and seek an audio element can participate. You could build a React player, a mobile app, or even a CLI player and they would all stay in sync.

Wrapping Up

The core insight of this project is that you don't need streaming infrastructure to build a radio station. If all your content is pre-recorded, which is the case for most community, charity, and niche radio stations, then the problem reduces to:

Store the schedule
Given the current time, compute what should be playing and where
Tell the player to seek to that position
Periodically re-sync to correct drift

The fmod() trick for loop synchronisation is the technique I'm most happy with. It's elegant, stateless, and trivially scalable. You could have a million listeners and the server computation is identical, one modulo operation and a walk through an array.

The full codebase includes the admin panel (media upload, library management, schedule builder, loop playlist with drag-and-drop reorder), the API endpoints, and the player. It runs on any standard PHP hosting with MySQL.

If you're building something similar, whether it's a community radio, a podcast-as-radio-station, or any "synchronised playback from pre-recorded content" system, the principles here apply directly. The sync algorithm doesn't care about your tech stack; it's just arithmetic.

Github Link: https://github.com/IAmMasterCraft/online-radio-system

Accelerating Web Performance with PHP and JavaScript

Boluwaji Akinsefunmi — Mon, 25 Mar 2024 14:11:01 +0000

Table of Content

Introduction
Understanding Lazy-Loading
- What is Lazy-Loading?
- Benefits of Lazy-Loading Images
Prerequisites
- Basic Knowledge Required
- Tools and Environment Setup
Analysing the Problem
- Identifying the Bottleneck in Web Performance
- Planning the Lazy-Loading Implementation
Lazy-Loading Implementation
- PHP Script for Lazy-Loading
- JavaScript for Lazy-Loading
- Integrating the Solution
- Usage Example:
Optimisation and Best Practices
- Additional Considerations
- Monitoring and Continuous Improvement
Results and Performance Gains
- Before and After Comparison
- Technical Insights
Summary and Conclusion
- Key Takeaways
- Future Considerations

Introduction

Managing the Ekiti Parapo UK website, a platform built with PHP without the crutch of any framework, presented a unique set of challenges and learning opportunities. As a charity organisation committed to fostering community and cultural connections, the need for a robust online presence was undeniable.

However, over time, the performance of the website began to decline, turning what should have been a smooth browsing experience into a test of patience for visitors.

Loading time was stretching to nearly two minutes for the homepage, you can literally go and boil water for tea while waiting for it to load, even on a decent 19Mbps internet connection, it was clear that a change was necessary.

A deep dive into the Chrome Developer Tools revealed an unexpected protagonist in this tale of dwindling performance: the images. High-quality, impactful images had always been central to the digital content on the platform, but they had also become the Achilles' heel of the site's speed.

The realisation brought back memories of frontend frameworks like NuxtJS, where lazy-loading images—a technique to delay loading off-screen images until needed—was a breeze. Missing these features in the current setup of the codebase, I was inspired to embark on a mission: to manually implement lazy-loading and reclaim the website's lost efficiency instead of starting afresh with NuxtJS.

This article chronicles my journey from identifying the problem to implementing a solution. Through a detailed exploration of lazy-loading with PHP and JavaScript, I hope to shed light on a path that can lead to significant performance improvements for any website facing similar issues.

Understanding Lazy-Loading

One innovative strategy stands out in the quest for optimal website performance is lazy-loading. This technique, at its core, involves deferring the loading of non-critical resources at page load time, instead waiting until they are actually needed. While it can be applied to various types of content, lazy-loading images is particularly impactful due to the significant bandwidth images typically consume.

What is Lazy-Loading?

Lazy-loading is a design pattern used to delay the initialisation of an object until the point at which it is needed. When applied to images on a website, it means that images outside of the viewport (the part of the webpage visible to the user) are not loaded until the user scrolls them into view. This approach can drastically reduce the initial load time of a page, improve user experience, and conserve data usage for users on limited data plans.

Benefits of Lazy-Loading Images

1. Improved Page Load Time: By loading only the images that are immediately visible, the amount of data the browser needs to fetch on the initial page load is reduced, leading to faster load times.
2. Reduced Server Load: Lazy-loading reduces the number of requests made to the server at one time, easing the load on the server and potentially saving bandwidth.
3. Enhanced User Experience: Users can start interacting with the content more quickly, which can improve engagement and reduce bounce rates.
4. SEO Advantages: Faster page load times are a factor in search engine rankings. By improving the speed of your site, you may also improve your site's visibility.

Prerequisites

Before diving into the implementation of lazy-loading images using PHP and JavaScript, it's important to ensure you have a solid foundation in the necessary technologies and concepts. This section outlines the prerequisites that will enable you to successfully apply the techniques discussed in this guide.

Basic Knowledge Required

1. PHP: A server-side scripting language used for web development. Familiarity with PHP syntax and basic programming concepts such as functions, loops, and arrays is essential.
2. JavaScript (JS): A client-side scripting language that enables dynamic content and interaction in web browsers. Understanding of DOM manipulation, event handling, and asynchronous programming (promises or async/await) is crucial.
3. HTML: The standard markup language for creating web pages. Knowledge of how to structure a webpage with HTML, including the use of <img /> tags, is necessary.
4. CSS (optional): Though not directly related to lazy-loading, basic knowledge of CSS can be helpful for styling placeholders and loading animations.

Tools and Environment Setup

1. Text Editor or IDE: A code editor such as Visual Studio Code, Sublime Text, or PHPStorm where you can write and edit your PHP and JavaScript code.
2. Local Development Server: A local server environment like XAMPP, WAMP, MAMP, or Docker to test your PHP scripts. PHP's built-in development server can also be used for simple testing.
3. Web Browser with Developer Tools: A modern web browser such as Google Chrome, Firefox, or Safari with developer tools for testing and debugging your code. Familiarity with the network tab and console in the browser's developer tools is beneficial.

Analysing the Problem

The journey toward implementing lazy-loading began with a critical examination of the website's performance issues. Utilising the Chrome Developer Tools, a key discovery was made that would pave the way for significant improvements.

Identifying the Bottleneck in Web Performance

The exploration started in the "Network" tab of the Chrome Developer Tools, focusing on the "Time" column to identify which requests were taking the longest to complete. This methodical approach led to an important realisation: the images were the main culprits behind the excessive load times.

The insight gained from sorting requests by their completion time highlighted the images' significant impact on the website's performance. This was a pivotal moment, underscoring the need for a solution that could address this specific challenge effectively.

Planning the Lazy-Loading Implementation

Armed with this knowledge, the plan to implement lazy-loading took shape with a clear focus:

1. Selection of Images: I decided to apply lazy-loading to all images that were not immediately visible upon page load, which happens to be all the images below the slider. This strategy aimed to prioritise the loading of content that the user would first interact with, thereby enhancing the overall user experience.

2. Placeholder Image Strategy: A critical aspect of the implementation was the introduction of a placeholder image. A low-size (72kb) placeholder, sourced from loading.io as gif image, was selected for its efficiency and its role in maintaining a smooth user experience while the actual images were being loaded.

3. Utilisation of the Intersection Observer API: The Intersection Observer API emerged as a central component of the lazy-loading strategy. Its ability to detect when an image enters the viewport without excessive resource consumption made it an ideal choice for triggering image loading precisely when needed.

4. Asynchronous Image Decoding: Recognising the potential for large images to freeze the browser during decoding, the strategy included the use of img.decode() to manage this process asynchronously. This approach ensured that the user interface remained responsive, even as high-quality images were being prepared for display.

Lazy-Loading Implementation

The implementation process is divided into two main parts: creating a PHP function to dynamically render lazy-loading-ready image tags and writing JavaScript to handle the lazy-loading logic.

PHP Script for Lazy-Loading

The first step is to create a PHP function that prepares your images for lazy-loading. This function will generate an <img /> tag with a data-src attribute holding the actual image URL and a placeholder image as the default src.

Creating the PHP Function:

<?php
function lazyLoad($path, $attributes = [])
{
    $classValue = isset($attributes['class']) ? $attributes['class'] . ' php-lazy-loading' : 'php-lazy-loading';
    $attributes['class'] = $classValue;
    $imgTag = '<img data-src="' . htmlspecialchars($path) . '" src="images/pre-load.gif"';
    foreach ($attributes as $key => $value) {
        $imgTag .= ' ' . htmlspecialchars($key) . '="' . htmlspecialchars($value) . '"';
    }
    $imgTag .= '>';
    return $imgTag;
}
?>

This function takes two parameters: the image path and an optional array of additional HTML attributes for the <img /> tag.
The class attribute is modified to include 'php-lazy-loading' class, which is used by the JavaScript to identify images that should be lazy-loaded.
A placeholder image (images/pre-load.gif) is set as the default image source.
The actual image path is stored in the data-src attribute to be loaded later by JavaScript.

JavaScript for Lazy-Loading

With the PHP function ready, the next step involves JavaScript to detect when the image should be loaded.

Implementing Intersection Observer:

<script>
document.addEventListener("DOMContentLoaded", function() {
    const lazyloadImages = document.querySelectorAll("img.php-lazy-loading");

    const imageObserver = new IntersectionObserver(function(entries, observer) {
        entries.forEach(function(entry) {
            if (entry.isIntersecting) {
                const image = entry.target;
                const img = new Image();
                img.src = image.dataset.src;
                img.decode().then(() => {
                    image.src = img.src;
                    image.onload = () => {
                        image.classList.remove("php-lazy-loading");
                    };
                    observer.unobserve(image);
                }).catch((error) => {
                    console.error("Image decoding failed", error);
                });
            }
        });
    }, {
        rootMargin: "0px 0px 200px 0px"
    });

    lazyloadImages.forEach(function(image) {
        imageObserver.observe(image);
    });
});
</script>

This script waits for the DOM to fully load before querying for images marked with the 'php-lazy-loading' class.
The IntersectionObserver is used to monitor these images and load them as they approach the viewport, specified by rootMargin.
Upon intersecting, the actual image is loaded asynchronously using the Image.decode() method, which helps prevent rendering jank.
Once loaded, the placeholder is replaced with the actual image, and the image is removed from the observer to stop watching it.

Integrating the Solution

To integrate this lazy-loading solution into your website, follow these steps:

1. Incorporate the code: Include the PHP file with the PHP function and JavaScript code on the page where images are rendered.

2. Apply Lazy-Loading to Images: Replace standard <img /> tags with calls to the lazyLoad() function, passing the appropriate image path and attributes.

Usage Example:

Replace:

<img
  class="img-fullwidth" 
  alt="260x230" 
  src='<?php echo "/admin/main/" . $row["picture"]; ?>'
  />

With:

<?php
include_once('util/load-image.php');

echo lazyLoad("admin/main/".$row['picture'], [
    'alt' => '260x230',
    'class' => 'img-fullwidth'
]);
?>

This example demonstrates how to use the lazyLoad() function within a PHP page, dynamically rendering an image with additional attributes like alt and class.

Optimisation and Best Practices

Implementing lazy-loading is a significant step towards improving your website's performance, but to maximise its benefits, consider the following optimisations and best practices:
1. Choosing Placeholder Images

Size and Format: Ensure that your placeholder images are small in file size to speed up initial page load times. Formats like SVG or highly compressed JPEGs can be good choices.
Visual Representation: Use placeholders that hint at the content of the lazy-loaded image. A blurred version of the original image or a generic loading icon can maintain layout stability and improve the user experience.

2. Setting Root Margins for the Intersection Observer

Root Margin Explained: The rootMargin property in the Intersection Observer API allows you to specify how far from the viewport you'd like to begin loading your images. This is akin to a buffer zone around the viewport.
Adjusting Root Margin: A positive value (e.g., "200px 0px") means the image will start loading before it enters the viewport, which can help ensure the image is loaded by the time the user sees it.

3. Error Handling and Image Decoding Failures

Graceful Fallbacks: Implement error handling for scenarios where an image fails to load or decode. This can include displaying a default error image or retrying the image load.
Asynchronous Decoding: The use of img.decode() in the JavaScript code ensures that decoding happens asynchronously, preventing the UI from freezing. Ensure that error handling is in place for browsers that do not support image decoding.

Additional Considerations

Lazy-Load Offscreen Iframes: Similar to images, iframes can also be lazy-loaded using the same Intersection Observer approach. This can further improve page load times, especially for pages with embedded videos or maps.
Avoid Lazy-Loading Everything: Be judicious in what you choose to lazy-load. Critical images above the fold should be loaded normally to ensure they are immediately visible to the user.
Test on Multiple Devices: Test your lazy-loading implementation across different devices and network conditions to ensure a consistent and smooth user experience.

Monitoring and Continuous Improvement

Performance Metrics: Use web performance monitoring tools to measure the impact of lazy-loading on your site.
Feedback Loop: Gather feedback from real users about their experience with the lazy-loaded images. User feedback can provide insights that automated tools cannot.

Results and Performance Gains

The implementation of lazy-loading images on the Ekiti Parapo UK website marks a significant milestone in the platform's evolution. By addressing the primary challenge of extended load times due to heavy image content, the initiative has yielded impressive results, enhancing both user experience and website performance.

Before and After Comparison

Initial Load Time: Prior to the implementation, the homepage took almost 2 minutes (around 102 seconds) to fully load. This sluggish performance was a barrier to user engagement and negatively impacted the overall user experience.

Post-Implementation Load Time: After integrating lazy-loading, the homepage load time dramatically reduced to approximately 9 seconds. This represents a whooping 91.18% reduction in load time, significantly surpassing initial expectations and setting a new benchmark for the website's performance.

Impact on User Experience
The improvement in load time has had a direct and positive impact on user experience. Visitors to the Ekiti Parapo UK website now enjoy a smoother, faster browsing experience, with images loading dynamically as they scroll through the content.

SEO Improvements
Faster page load times are a critical factor in search engine optimisation (SEO). By significantly reducing the load time of the homepage, the website stands a better chance of achieving higher rankings in search engine results pages (SERPs).

Technical Insights

The transition to lazy-loading required a detailed technical implementation, as outlined in previous sections. The process illuminated several key insights:

1. Efficiency of Intersection Observer API: The use of the Intersection Observer API proved to be highly efficient and effective for detecting when images enter the viewport, minimising unnecessary image loads.
2. Asynchronous Image Decoding: Implementing asynchronous image decoding helped prevent browser freezes, ensuring a smooth user experience even as high-quality images were loaded.
3. Placeholder Strategy: The strategic use of placeholders maintained the layout integrity during image loading, enhancing the perceived performance for users.

Summary and Conclusion

The journey of optimising the Ekiti Parapo UK website by implementing lazy-loading for images has been both challenging and rewarding. Beginning with a pressing need to address significantly prolonged load times, the initiative culminated in a remarkable improvement in performance, user experience, and potentially SEO rankings. The success of this project underscores several key points and lessons for the web development community.

Key Takeaways

1. Performance Optimisation is Crucial: In the digital age, where user attention spans are short, and competition is fierce, optimising website performance is not just beneficial but essential. The dramatic reduction in load time from nearly 2 minutes to just 9 seconds illustrates the tangible benefits that can be achieved through focused optimisation efforts.

2. Lazy-Loading as an Effective Strategy: The implementation of lazy-loading has proven to be a highly effective strategy for improving website speed and efficiency. By loading images only as they are needed, websites can significantly reduce initial load times and resource consumption, enhancing the user experience.

3. Technical Implementation is Accessible: With the right approach and understanding, incorporating sophisticated performance optimisations like lazy-loading is achievable even outside of modern development frameworks. The use of PHP and JavaScript, as demonstrated, allows for significant improvements with manageable complexity.

4. Continuous Improvement and Adaptation: The web development landscape is ever-evolving, and so are the techniques and strategies for optimization.

Future Considerations

Looking ahead, there is potential to further refine and expand the lazy-loading implementation. Exploring advanced techniques, such as adaptive image loading based on network conditions, could provide additional performance benefits and user experience enhancements.