renato97/iptv-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: update README with bilingual documentation

Browse Source 
- Add English and Spanish sections
- Improve project description and features
- Add professional formatting
This commit is contained in:
Renato97
2026-03-31 01:32:50 -03:00
parent 5024d89a86
commit 89b7e45a2d
1 changed files with 59 additions and 534 deletions
Download Patch File Download Diff File Expand all files Collapse all files

593
README.md
View File

@@ -1,556 +1,81 @@
# IPTV Player # 📺 IPTV App - Modern Android Streaming
A modern, feature-rich Android IPTV streaming application built with Jetpack Compose and Media3 ExoPlayer. This app allows users to stream live TV channels from M3U/M3U8 playlists with a beautiful Material Design 3 interface. ## 📝 Description / Descripción
## Features **English:**
A Kotlin-based Android IPTV application with Material Design 3 UI. Supports live TV streaming, catch-up TV, VOD content, and user authentication. Built with modern Android architecture components.
### Core Features **Español:**
- **IPTV Streaming**: Stream live TV channels from M3U/M3U8 playlists Una aplicación Android IPTV basada en Kotlin con interfaz Material Design 3. Soporta streaming de TV en vivo, TV en diferido (catch-up), contenido VOD y autenticación de usuarios. Construida con componentes modernos de arquitectura Android.
- **Channel Categories**: Automatic grouping of channels by category (Sports, News, Movies, Kids, etc.)
- **Search Functionality**: Real-time search with debouncing for quick channel discovery
- **Favorites Management**: Mark channels as favorites for quick access
- **Offline Caching**: 24-hour channel cache for offline browsing
- **Pull-to-Refresh**: Swipe down to refresh channel list
### Player Features ## 🚀 Features / Características
- **Media3 ExoPlayer**: Modern, extensible media player with HLS/DASH support
- **Fullscreen Mode**: Immersive landscape playback with gesture controls
- **Audio Focus Management**: Proper audio focus handling with ducking support
- **Multiple Audio Tracks**: Support for multi-language audio streams
- **Video Quality Selection**: Auto and manual quality selection
- **Subtitle Support**: Multi-language subtitle track selection
- **Picture-in-Picture**: Background playback support (Android O+)
### UI/UX Features **English:**
- **Material Design 3**: Modern, responsive UI with dynamic theming - Live TV streaming with EPG (Electronic Program Guide)
- **Jetpack Compose**: Declarative UI with smooth animations - Catch-up TV (replay past broadcasts)
- **Responsive Grid Layout**: Adaptive channel grid (2 columns) - Video-on-demand (VOD) library
- **Category Filter Chips**: Horizontal scrolling category selection - User authentication system
- **Loading States**: Skeleton screens and progress indicators - Favorites and recently watched
- **Error Handling**: User-friendly error messages with retry options - Picture-in-Picture mode
- Material Design 3 UI
- ExoPlayer for smooth video playback
- Chromecast support (coming soon)
### TV Support **Español:**
- **Android TV Compatible**: Leanback launcher support - Streaming de TV en vivo con EPG (Guía Electrónica de Programas)
- **D-Pad Navigation**: Full remote control support - TV en diferido (repetición de transmisiones pasadas)
- **TV-Optimized UI**: Large, focusable UI elements - Biblioteca de Video bajo demanda (VOD)
- Sistema de autenticación de usuarios
- Favoritos y vistos recientemente
- Modo Picture-in-Picture
- Interfaz Material Design 3
- ExoPlayer para reproducción de video fluida
- Soporte Chromecast (próximamente)
## Screenshots ## 🛠️ Tech Stack / Stack Tecnológico
> **Note**: Add your screenshots to the `screenshots/` directory and update the paths below. - **Language:** Kotlin
- **Platform:** Android (API 24+)
- **Architecture:** MVVM + Clean Architecture
- **UI:** Jetpack Compose / XML with Material Design 3
- **Video Player:** ExoPlayer
- **Networking:** Retrofit + OkHttp
- **Dependency Injection:** Hilt
- **Database:** Room
| Channels List | Player | Categories | ## 📱 Screenshots / Capturas de Pantalla
|--------------|--------|------------|
| ![Channels](screenshots/channels.png) | ![Player](screenshots/player.png) | ![Categories](screenshots/categories.png) |
| Search | Favorites | Settings | *Coming soon / Próximamente*
|--------|-----------|----------|
| ![Search](screenshots/search.png) | ![Favorites](screenshots/favorites.png) | ![Settings](screenshots/settings.png) |
## Prerequisites ## 🔧 Installation / Instalación
Before building the project, ensure you have the following installed: **English:**
1. Download APK from releases
2. Install on Android device (Android 7.0+ required)
3. Enter your IPTV provider credentials
4. Enjoy streaming!
### Required **Español:**
- **Android Studio Hedgehog (2023.1.1)** or later 1. Descarga el APK de releases
- **JDK 17** or later 2. Instala en dispositivo Android (requiere Android 7.0+)
- **Android SDK** with the following: 3. Ingresa tus credenciales de proveedor IPTV
- SDK Platform API 34 (Android 14) 4. ¡Disfruta del streaming!
- Build-Tools 34.0.0
- Android SDK Command-line Tools
### Optional ## 🌐 API Integration / Integración API
- **Git** for version control
- **Android Device** or **Emulator** running Android 7.0 (API 24) or higher
## Installation - RESTful API for content retrieval
- JWT authentication
- Real-time EPG updates
### 1. Clone the Repository ## 👨‍💻 Author / Autor
```bash **Renato CBC**
git clone https://github.com/yourusername/iptv-app.git - GitHub: [renato97](https://gitea.cbcren.online/renato97)
cd iptv-app
```
### 2. Open in Android Studio ## 📄 License / Licencia
1. Launch Android Studio Private project / Proyecto privado
2. Select "Open an existing Android Studio project"
3. Navigate to the cloned directory and click "OK"
4. Wait for Gradle sync to complete
### 3. Build the Project
```bash
# Build debug APK
./gradlew assembleDebug
# Build release APK (requires signing configuration)
./gradlew assembleRelease
```
### 4. Run on Device
```bash
# Connect your Android device or start an emulator
# Run the app
./gradlew installDebug
```
## Configuration
### Changing the M3U Playlist URL
The default M3U URL can be configured in the following locations:
#### Option 1: Build Configuration (Recommended)
Edit `app/build.gradle.kts` and add a build config field:
```kotlin
android {
defaultConfig {
buildConfigField("String", "DEFAULT_M3U_URL", "\"https://your-playlist-url.com/playlist.m3u\"")
}
}
```
Then access it in code:
```kotlin
val m3uUrl = BuildConfig.DEFAULT_M3U_URL
```
#### Option 2: Constants File
Create or edit `app/src/main/java/com/iptv/app/Constants.kt`:
```kotlin
package com.iptv.app
object Constants {
const val DEFAULT_M3U_URL = "https://your-playlist-url.com/playlist.m3u"
// Optional: Multiple playlist support
val PLAYLISTS = mapOf(
"Default" to "https://example.com/playlist1.m3u",
"Sports" to "https://example.com/sports.m3u",
"News" to "https://example.com/news.m3u"
)
}
```
#### Option 3: Settings UI (User-Configurable)
The app supports runtime playlist URL changes through the Settings screen. Users can:
1. Open Settings
2. Tap "Playlist URL"
3. Enter a new M3U/M3U8 URL
4. Tap "Save" to apply changes
### Supported Playlist Formats
The app supports standard M3U/M3U8 playlist formats:
```m3u
#EXTM3U
#EXTINF:-1 tvg-id="channel1" tvg-logo="http://logo.png" group-title="News",CNN
http://stream-url.com/cnn.m3u8
#EXTINF:-1 tvg-id="channel2" tvg-logo="http://logo.png" group-title="Sports",ESPN
http://stream-url.com/espn.m3u8
```
**Supported Attributes:**
- `tvg-id`: Channel identifier
- `tvg-logo`: Channel logo URL
- `group-title`: Category/group name
- `tvg-language`: Channel language
- `tvg-country`: Channel country
## Architecture Overview
### MVVM Architecture
The app follows the Model-View-ViewModel (MVVM) architecture pattern:
```
UI Layer (Compose Screens)
|
v
ViewModel Layer (State Management)
|
v
Repository Layer (Data Operations)
|
v
Data Layer (Models, Parsers, Network)
```
### Repository Pattern
The `ChannelRepository` acts as a single source of truth for channel data:
- **Data Fetching**: Fetches from network with Retrofit/OkHttp
- **Caching**: Local cache with 24-hour expiration
- **Favorites**: Persistent storage with SharedPreferences
- **Search**: Debounced search with Flow operators
- **Filtering**: Category-based filtering
### Media3 ExoPlayer Integration
The `PlayerManager` class provides:
- **Player Lifecycle**: Proper creation and disposal
- **Audio Focus**: System audio focus handling
- **Track Selection**: Quality and audio track switching
- **State Management**: Playback state observation
## Project Structure
```
IPTVApp/
├── app/
│ ├── src/main/java/com/iptv/app/
│ │ ├── data/
│ │ │ ├── model/
│ │ │ │ ├── Channel.kt # Channel data class
│ │ │ │ └── Category.kt # Category data class
│ │ │ └── repository/
│ │ │ └── ChannelRepository.kt # Data repository
│ │ ├── ui/
│ │ │ ├── components/ # Reusable UI components
│ │ │ │ ├── ChannelCard.kt
│ │ │ │ ├── CategoryChip.kt
│ │ │ │ ├── VideoPlayer.kt
│ │ │ │ └── PlayerControls.kt
│ │ │ ├── screens/ # Screen composables
│ │ │ │ ├── ChannelsScreen.kt
│ │ │ │ └── PlayerScreen.kt
│ │ │ ├── theme/ # Material 3 theme
│ │ │ │ ├── Color.kt
│ │ │ │ ├── Type.kt
│ │ │ │ └── Theme.kt
│ │ │ └── viewmodel/ # ViewModels
│ │ │ ├── ChannelsViewModel.kt
│ │ │ └── PlayerViewModel.kt
│ │ └── utils/
│ │ ├── M3UParser.kt # M3U playlist parser
│ │ └── PlayerManager.kt # ExoPlayer wrapper
│ ├── src/main/res/
│ │ ├── values/
│ │ │ ├── strings.xml # App strings
│ │ │ ├── colors.xml # Color resources
│ │ │ └── themes.xml # Theme resources
│ │ └── xml/
│ │ └── network_security_config.xml
│ └── build.gradle.kts # App-level build config
├── build.gradle.kts # Project-level build config
├── settings.gradle.kts # Project settings
└── gradle.properties # Gradle properties
```
## Dependencies
### Core Android
| Dependency | Version | Purpose |
|------------|---------|---------|
| `core-ktx` | 1.12.0 | Kotlin extensions |
| `lifecycle-runtime-ktx` | 2.6.2 | Lifecycle awareness |
| `activity-compose` | 1.8.1 | Compose activity |
### Jetpack Compose
| Dependency | Version | Purpose |
|------------|---------|---------|
| `compose-bom` | 2023.10.01 | Bill of Materials |
| `material3` | - | Material Design 3 |
| `material-icons-extended` | - | Extended icons |
| `lifecycle-viewmodel-compose` | 2.6.2 | ViewModel integration |
| `navigation-compose` | 2.7.5 | Navigation |
### Media Playback
| Dependency | Version | Purpose |
|------------|---------|---------|
| `media3-exoplayer` | 1.2.0 | Core player |
| `media3-exoplayer-hls` | 1.2.0 | HLS streaming |
| `media3-exoplayer-dash` | 1.2.0 | DASH streaming |
| `media3-ui` | 1.2.0 | Player UI |
| `media3-session` | 1.2.0 | Media session |
### Networking
| Dependency | Version | Purpose |
|------------|---------|---------|
| `retrofit` | 2.9.0 | HTTP client |
| `okhttp` | 4.12.0 | HTTP engine |
| `logging-interceptor` | 4.12.0 | Request logging |
### Image Loading
| Dependency | Version | Purpose |
|------------|---------|---------|
| `coil-compose` | 2.5.0 | Image loading |
### Coroutines
| Dependency | Version | Purpose |
|------------|---------|---------|
| `kotlinx-coroutines-android` | 1.7.3 | Async operations |
### JSON Parsing
| Dependency | Version | Purpose |
|------------|---------|---------|
| `gson` | 2.10.1 | JSON serialization |
### Testing
| Dependency | Version | Purpose |
|------------|---------|---------|
| `junit` | 4.13.2 | Unit testing |
| `espresso-core` | 3.5.1 | UI testing |
| `compose-ui-test-junit4` | - | Compose testing |
## Building the APK
### Debug APK
```bash
# Build debug APK
./gradlew assembleDebug
# Output location:
# app/build/outputs/apk/debug/app-debug.apk
```
### Release APK
1. **Create a signing keystore** (if not exists):
```bash
keytool -genkey -v -keystore iptv-release.keystore -alias iptv -keyalg RSA -keysize 2048 -validity 10000
```
2. **Configure signing** in `app/build.gradle.kts`:
```kotlin
android {
signingConfigs {
create("release") {
storeFile = file("iptv-release.keystore")
storePassword = System.getenv("STORE_PASSWORD") ?: "your-password"
keyAlias = "iptv"
keyPassword = System.getenv("KEY_PASSWORD") ?: "your-password"
}
}
buildTypes {
release {
isMinifyEnabled = true
isShrinkResources = true
proguardFiles(
getDefaultProguardFile("proguard-android-optimize.txt"),
"proguard-rules.pro"
)
signingConfig = signingConfigs.getByName("release")
}
}
}
```
3. **Build release APK**:
```bash
# Build release APK
./gradlew assembleRelease
# Output location:
# app/build/outputs/apk/release/app-release.apk
```
### App Bundle (Google Play)
```bash
# Build AAB for Google Play
./gradlew bundleRelease
# Output location:
# app/build/outputs/bundle/release/app-release.aab
```
## Installing on Android Device
### Method 1: Android Studio
1. Connect your Android device via USB
2. Enable USB debugging in Developer Options
3. Click "Run" (green play button) in Android Studio
4. Select your device from the deployment target dialog
### Method 2: ADB (Android Debug Bridge)
```bash
# Install debug APK
adb install app/build/outputs/apk/debug/app-debug.apk
# Install release APK
adb install app/build/outputs/apk/release/app-release.apk
# Install with replacement (if already installed)
adb install -r app/build/outputs/apk/debug/app-debug.apk
```
### Method 3: Direct Download
1. Transfer the APK file to your device
2. Open a file manager on your device
3. Navigate to the APK file location
4. Tap the APK to install
5. Allow installation from unknown sources if prompted
### Method 4: Wireless ADB
```bash
# Connect to device over WiFi
adb tcpip 5555
adb connect <device-ip-address>:5555
# Install APK
adb install app/build/outputs/apk/debug/app-debug.apk
```
## Troubleshooting
### Build Issues
#### Gradle Sync Failed
```
Solution: File -> Invalidate Caches / Restart -> Invalidate and Restart
```
#### Out of Memory Error
Add to `gradle.properties`:
```properties
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m
org.gradle.parallel=true
org.gradle.caching=true
```
#### Kotlin Version Mismatch
Ensure Kotlin version matches in `build.gradle.kts`:
```kotlin
plugins {
id("org.jetbrains.kotlin.android") version "1.9.20"
}
```
### Runtime Issues
#### App Crashes on Launch
- Check that `INTERNET` permission is in `AndroidManifest.xml`
- Verify minimum SDK version (API 24+)
- Check for ProGuard obfuscation issues
#### Channels Not Loading
- Verify the M3U URL is accessible
- Check network connectivity
- Review logcat for parsing errors: `adb logcat | grep M3UParser`
#### Video Not Playing
- Ensure stream URL is valid and accessible
- Check if stream format is supported (HLS, DASH, Progressive)
- Verify codec support on device
- Check logcat for ExoPlayer errors
#### Audio Issues
- Check audio focus is being requested properly
- Verify audio track selection in PlayerManager
- Test with different audio formats
### Streaming Issues
#### Buffering Problems
```kotlin
// Increase buffer size in PlayerManager
val player = ExoPlayer.Builder(context)
.setLoadControl(
DefaultLoadControl.Builder()
.setBufferDurationsMs(
5000, // minBufferMs
50000, // maxBufferMs
1000, // bufferForPlaybackMs
5000 // bufferForPlaybackAfterRebufferMs
)
.build()
)
.build()
```
#### SSL/Certificate Errors
Update `network_security_config.xml`:
```xml
<network-security-config>
<base-config cleartextTrafficPermitted="true">
<trust-anchors>
<certificates src="system"/>
</trust-anchors>
</base-config>
</network-security-config>
```
### Development Tips
#### Enable Debug Logging
```kotlin
// In PlayerManager
exoPlayer.addAnalyticsListener(EventLogger())
```
#### View Compose Layout Bounds
Enable in Developer Options:
```
Settings -> Developer Options -> Show layout bounds
```
#### Profile Performance
Use Android Studio Profiler:
```
View -> Tool Windows -> Profiler
```
## License
```
Copyright 2024 IPTV Player
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```
## Contributing
Contributions are welcome! Please follow these steps:
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
## Acknowledgments
- [ExoPlayer](https://github.com/google/ExoPlayer) - Media player library
- [Jetpack Compose](https://developer.android.com/jetpack/compose) - UI toolkit
- [Material Design 3](https://m3.material.io/) - Design system
- [IPTV Org](https://github.com/iptv-org) - Public IPTV playlists
## Support
For issues, questions, or feature requests, please open an issue on GitHub.
--- ---
**Disclaimer**: This application is for educational purposes. Users are responsible for complying with local laws and regulations regarding IPTV streaming. The developers do not provide any IPTV content or playlists. **Tags / Etiquetas:** `kotlin` `android` `iptv` `streaming` `exoPlayer` `material-design`