📺 Plex Contribution Graph

Transform your Plex movie watch history into a beautiful GitHub-style contribution graph

---

✨ Features

Feature	Description
🎨 Light & Dark Themes	Automatically adapts to GitHub's theme preference
📊 Activity Heatmap	GitHub-style contribution graph showing movie activity
☁️ Plex Cloud Integration	Fetches watch history via community.plex.tv, no port-forwarding required
🎬 Movies Only	Focused on your film collection (series support coming later)
📅 Multi-Year Support	Generate graphs spanning multiple years
💬 Interactive Tooltips	Hover over cells to see film details with release years
🔄 Daily Updates	Automated updates via GitHub Actions

---

🚀 Quick Start

1. Fork this Repository

Click the Fork button at the top-right of this page.

2. Get Your Plex Token

You need your X-Plex-Token. Find it in your browser's network tab when logged into Plex Web, or follow this guide.

3. Configure Secrets

Go to Settings > Secrets and variables > Actions and add:

• PLEX_TOKEN: Your Plex authentication token
• PLEX_USER: Your Plex username

4. Update Workflow Configuration

Edit .github/workflows/update-graph.yml and set your desired years.

5. Enable GitHub Actions

Go to Actions tab → Enable workflows if prompted.

6. Run the Workflow

The graph updates daily at midnight UTC, or trigger manually via the Actions tab.

Note: You must have "Sync My Watch State and Ratings" enabled in your Plex account settings.

---

📖 CLI Usage

# Install dependencies
npm install

# Basic usage (requires PLEX_TOKEN in .env or environment)
node src/cli.js -y 2025

# With options
node src/cli.js [options]

Arguments

Flag	Description	Default
-y <years>	Year(s) to generate, comma-separated (e.g. 2025,2024)	Current year
-w <day>	Week start: sunday or monday	sunday
-o <path>	Output path (without extension)	images/plex-graph
-g <bool>	Enable username gradient: true or false	true
-p	Export PNG files in addition to SVG	Disabled

Examples

# Single year
node src/cli.js -y 2025

# Multiple years
node src/cli.js -y 2025,2024

# Start week on Monday, with PNG export
node src/cli.js -y 2025 -w monday -p

# Custom output path
node src/cli.js -y 2025 -o images/my-graph

---

🔧 GitHub Actions Setup

Workflow File

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

name: Update Plex Graph

# ╔════════════════════════════════════════════════════════════════╗
# ║  CONFIGURATION - Edit these values for your Plex profile       ║
# ╚════════════════════════════════════════════════════════════════╝
env:
  YEARS: "2025"                        # Years to generate (e.g. "2025,2024")
  EXPORT_PNG: "false"                  # Set to "true" to also generate PNG files
  WEEK_START: "sunday"                 # "sunday" or "monday"
  GRADIENT: "true"                     # "true" for colored name, "false" for white

on:
  schedule:
    - cron: "0 0 * * *"   # Daily at midnight UTC
  workflow_dispatch:       # Manual trigger

permissions:
  contents: write

jobs:
  update-graph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - run: npm ci
      
      - name: Generate Graph
        env:
          PLEX_TOKEN: ${{ secrets.PLEX_TOKEN }}
        run: |
          CMD="node src/cli.js -o images/plex-graph"
          
          if [ -n "${{ env.YEARS }}" ]; then CMD="$CMD -y ${{ env.YEARS }}"; fi
          if [ "${{ env.WEEK_START }}" = "monday" ]; then CMD="$CMD -w monday"; fi
          if [ "${{ env.GRADIENT }}" = "false" ]; then CMD="$CMD -g false"; fi
          if [ "${{ env.EXPORT_PNG }}" = "true" ]; then CMD="$CMD -p"; fi
          
          echo "Running: $CMD"
          eval $CMD

      - name: Commit and Push
        run: |
          git config --global user.name 'github-actions[bot]'
          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
          git add images/
          
          if git diff --staged --quiet; then
            echo "No changes to commit"
          else
            TIMESTAMP=$(date -u +"%Y-%m-%d %H:%M UTC")
            git commit -m "Update Plex graph - $TIMESTAMP"
            git push
          fi

Required Secrets

Secret	Description
PLEX_TOKEN	Your Plex authentication token

---

📂 Project Structure

plex-graph/
├── .github/
│   └── workflows/
│       └── update-graph.yml  # GitHub Actions workflow
├── fonts/
│   ├── Inter-Bold.woff2
│   ├── Inter-Medium.woff2
│   ├── Inter-Regular.woff2
│   └── Inter-SemiBold.woff2
├── images/
│   ├── plex-graph-2025-dark.svg
│   └── plex-graph-2025-light.svg
├── src/
│   ├── cli.js                # CLI entry point
│   ├── fetcher.js            # Plex API data fetching
│   ├── generator.js          # SVG generation
│   ├── stats.js              # Statistics calculations
│   └── exporter.js           # PNG export functionality
├── plex-logo.svg             # Plex branding
├── package.json
└── README.md

---

🖼️ Embed in Your README

Add this to your profile README to display the graph with automatic theme switching:

<p align="center">
  <a href="https://www.plex.tv/" target="_blank">
    <picture>
      <source
        media="(prefers-color-scheme: dark)"
        srcset="https://github.com/YOUR_GITHUB_USERNAME/plex-graph/blob/main/images/plex-graph-2025-dark.svg"
      />
      <source
        media="(prefers-color-scheme: light)"
        srcset="https://github.com/YOUR_GITHUB_USERNAME/plex-graph/blob/main/images/plex-graph-2025-light.svg"
      />
      <img
        alt="Plex contribution graph"
        src="https://github.com/YOUR_GITHUB_USERNAME/plex-graph/blob/main/images/plex-graph-2025-light.svg"
      />
    </picture>
  </a>
</p>

Replace YOUR_GITHUB_USERNAME with your GitHub username.

---

🛠️ Requirements

• Node.js v18 or higher
• Plex account with "Sync Watch State" enabled
• GitHub account with Actions enabled (for automated updates)

---

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests

---

📄 License

MIT License - see LICENSE for details.