DulceCast

A modern IPTV streaming application that allows you to stream your favorite channels, movies, and shows in one place. Built with Next.js, React, and TypeScript for a smooth streaming experience.

Features

🎬 Streaming & Playback

• Multi-format Support: Supports HLS (.m3u8) and MPEG-TS streams
• Quality Selection: Automatic quality detection and manual quality switching (HEVC, Full HD, HD, Low)
• Full-Screen Player: Immersive viewing experience with custom controls
• Continue Watching: Resume playback from where you left off
• VOD Progress Tracking: Automatically saves and restores your playback position for pre-recorded content
• Visual Progress Indicators: Red progress bars on channel cards for partially watched content

📺 Channel Management

• M3U Playlist Support: Load channels from standard M3U playlist files
• Channel Categories: Browse channels organized by groups
• Favorites System: Save and organize your favorite channels
• Channel Search: Quickly find channels by name
• Per-Playlist Settings: Independent favorites, history, and progress for each IPTV provider

📅 Program Guide

• EPG Integration: Electronic Program Guide support for viewing schedules
• Program Information: See what's currently playing and upcoming shows

🎨 User Interface

• Modern Design: Clean, dark-themed interface optimized for streaming
• Responsive Hero Section: Dynamic scaling for long channel names and mobile-friendly layout
• Responsive Layout: Works seamlessly on desktop and mobile devices
• Smooth Animations: Framer Motion powered transitions and interactions
• Accessibility: Built with accessibility best practices

🔧 Technical Features

• Proxy API: Built-in proxy for handling CORS and stream routing
• Custom Error Handling: Branded "Stream Unavailable" screens for provider-related playback issues
• State Management: Zustand with persistent storage and URL-hashed playlist settings
• Type Safety: Full TypeScript implementation for reliability
• Performance: Optimized with Next.js App Router, lazy loading, and throttled progress saving

Getting Started

Prerequisites

• Bun (v1.0+)
• A valid M3U playlist URL (from your IPTV provider)
• Optional: EPG (XMLTV) URL for program guide

Installation

1. Clone the repository:

git clone <repository-url>
cd dulcecast

2. Install dependencies:

bun install

3. Start the development server:

bun dev

4. Open http://localhost:3000 in your browser.

Configuration

On first launch, you'll need to configure your streaming sources:

1. Playlist URL: Enter your M3U playlist URL
2. EPG URL (optional): Enter your EPG data URL for program information
3. Save & Start Watching: Your channels will be loaded and organized

Usage

Browsing Channels

• For You: Personalized recommendations and continue watching
• All Channels: Complete channel list organized by categories
• Favorites: Your saved favorite channels

Watching Content

• Click any channel to start streaming
• VOD Resume: Automatically picks up where you left off on movies and episodes
• Progress Bars: Easily identify partially watched content with visual red bars
• Use quality selector for different stream qualities
• Full-screen mode available for immersive viewing
• Channel switching with keyboard navigation

Managing Favorites

• Click the heart icon on any channel to add to favorites
• Access favorites from the dedicated tab
• Remove channels from favorites anytime

Project Structure

dulcecast/
├── app/                    # Next.js app directory
│   ├── api/proxy/         # Stream proxy API
│   ├── globals.css        # Global styles
│   └── layout.tsx         # Root layout
├── assets/                # Static image assets (logo, etc.)
├── components/            # React components
│   ├── browse/           # Channel browsing components
│   ├── login/            # Authentication components
│   ├── player/           # Video player & error components
│   ├── ui/               # Reusable UI components
│   └── views/            # Main view components
├── contexts/             # React contexts for state management
├── hooks/                # Custom React hooks
├── lib/                  # Utility functions and parsers
├── public/               # Publicly served static files
├── store/                # Zustand state stores
├── types/                # TypeScript type definitions
└── README.md             # Project documentation

Technology Stack

• Frontend: Next.js 16, React 19, TypeScript
• Styling: Tailwind CSS (v4), Radix UI components
• State Management: Zustand (Persist), React Context
• Video Playback: HLS.js, mpegts.js
• Animations: Framer Motion
• Icons: Lucide React
• Package Manager: Bun
• HTTP Client: Axios

Development

Available Scripts

• bun dev - Start development server
• bun build - Build for production
• bun start - Start production server
• bun lint - Run ESLint

Key Components

• LoginView: Handles playlist and EPG URL input
• BrowseView: Main channel browsing interface
• FullScreenVideoPlayer: Video playback with controls
• ChannelCarousel/Grid: Channel display components

API Routes

• /api/proxy - Stream proxy for CORS handling

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Security Note

This application acts as a client for IPTV streams. Ensure you have proper authorization to access the streams you configure. DulceCast does not provide or host any streaming content.

License

This project is private and proprietary.

Support

For support or questions, please check the documentation or create an issue in the repository.

---

Best viewed with DulceCast - Your ultimate streaming companion.