Skip to content

README.md

Latest commit

 

History

History
164 lines (111 loc) · 4.97 KB

README.md

File metadata and controls

164 lines (111 loc) · 4.97 KB

YouTube Chunker

A Progressive Web App (PWA) for playing specific segments of YouTube videos with custom start times and durations. Built with React, TypeScript, and Material-UI.

✨ Features

  • 📹 Video Segment Playback: Play YouTube videos starting at any point with a defined duration
  • ⏱️ Timer-Based Control: Automatically stops playback after the specified duration
  • 💾 State Persistence: Tracks playback position across sessions using localStorage
  • 🎯 Progress Tracking: Calculates and updates elapsed time and start position automatically
  • 📱 PWA Support: Install as a standalone app on any device
  • 🎨 Modern UI: Clean, responsive interface built with Material-UI
  • 🌙 Dark Theme: Easy-on-the-eyes dark mode design

🛠️ Tech Stack

  • Framework: React 19 with TypeScript
  • Build Tool: Vite 7 with SWC for Fast Refresh
  • State Management: Redux Toolkit with redux-persist (localStorage)
  • UI Library: Material-UI (MUI) v7 with Emotion styling
  • YouTube Integration: react-youtube library
  • Testing: Vitest with React Testing Library
  • PWA: vite-plugin-pwa with service worker support

Demo

You can see running application on Github Pages.

🚀 Getting Started

Prerequisites

  • Node.js (v18 or higher recommended)
  • npm or yarn

Installation

  1. Clone the repository:
git clone https://github.com/kosinal/youtube-chunk
cd youtube-chunk
  1. Install dependencies:
npm install
  1. Start the development server:
npm run dev
  1. Open your browser to http://localhost:5173

📝 Available Scripts

# Start development server with Hot Module Replacement
npm run dev

# Build for production (includes TypeScript type checking)
npm run build

# Preview production build locally
npm run preview

# Run all tests with Vitest
npm test

# Run tests with UI
npm run test:ui

# Run tests with coverage report
npm run test:coverage

# Run ESLint
npm run lint

# Fix ESLint issues automatically
npm run lint:fix

# Format code with Prettier
npm run format

# Check code formatting without making changes
npm run format:check

# Run complete quality check (format, lint, test, build)
npm run check

💡 Usage

  1. Enter YouTube URL: Paste any YouTube video URL (supports multiple formats: watch, embed, shorts, youtu.be)
  2. Set Start Time: Specify when the video should begin (in minutes)
  3. Set Duration: Define how long the segment should play (in minutes)
  4. Play: Click play to start the video segment
  5. Automatic Tracking: The app automatically:
    • Validates start time doesn't exceed video length
    • Stops playback after the specified duration
    • Updates start position based on elapsed time
    • Saves state to localStorage for persistence

🔧 Key Architecture Details

State Management

The app uses Redux Toolkit with redux-persist for localStorage persistence:

  • playerSlice: Manages video URL, start time, duration, playback state, timestamp tracking, and video list
  • redux-persist: Automatically saves entire Redux state to localStorage with whitelist configuration
  • State Rehydration: On app load, state is restored from localStorage using persistStore

Video Playback Logic

  • Timer-Based Control: Uses setTimeout to automatically pause after duration expires
  • Progress Calculation: Tracks elapsed time and updates start position accordingly
  • URL Parsing: Supports multiple YouTube URL formats via extractVideoId() helper
  • Validation: Prevents start time from exceeding video length

PWA Configuration

  • Manifest: Configured in vite.config.ts with theme colors and app metadata
  • Service Worker: Auto-generated with registerType: "autoUpdate" for automatic updates
  • Update Notification: Shows notification when new version is available with option to update
  • Cache Versioning: Cache ID includes package.json version for automatic cache invalidation
  • Runtime Caching: Network-first for YouTube API, cache-first for images, network-first for HTML
  • Offline Support: Assets cached for offline functionality
  • Install Prompt: Users can install app on any device
  • Auto Update Check: Service worker checks for updates every hour

🌐 Deployment

The app is configured for GitHub Pages deployment:

  1. Build the project:
npm run build

  1. The dist/ folder contains the production build

  2. Base path is set to /youtube-chunk/ in vite.config.ts

  3. Deploy the dist/ folder to your hosting service (GitHub Pages, Netlify, Vercel, etc.)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is open source and available under the GNU GENERAL PUBLIC LICENSE.

🙏 Acknowledgments