Flow - Modern YouTube Client

A modern, feature-rich YouTube client for Android built with Jetpack Compose

Table of Contents

• Development Status
• Features
  • Video Streaming
  • Music Player
  • Search & Discovery
  • Themes & Customization
  • User Interface
  • Library Management
  • Privacy & Data
• Architecture
  • Tech Stack
  • Project Structure
• Getting Started
  • Prerequisites
  • Installation
• Releasing
• Support & Donations
• Roadmap
  • High Priority
  • Core Features
  • User Experience
  • Technical Improvements
  • Future Ideas
• Contributing
• Acknowledgments
• License
• Contact & Support
• Troubleshooting
• Star History

---

⚠️ Development Status

Flow is currently under active development. Please note:

• 🐛 Some features may be incomplete or unstable
• 📊 Still optimizing performance and user experience

---

✨ Features

🎥 Video Streaming

• High-quality video playback with ExoPlayer
• Multiple quality options (Auto, 1080p, 720p, 480p, 360p)
• Fullscreen support with landscape mode
• Picture-in-Picture (PiP) mode
• Background playback
• Video chapters support
• Playback speed control (0.25x - 2x)
• Auto-play next video
• Gesture Controls: Left swipe for brightness, right swipe for volume
• Subtitles Support: SRT/VTT formats with animated display
• Subtitles Customization: Font size, color, background
• Enhanced Controls: Quality and subtitles badges at top
• Professional UI: Loading states, smooth animations, and visual feedback

🎵 Music Player

• Dedicated music player with YouTube Music integration
• Enhanced UI with album art and visualizations
• Queue management (add, remove, reorder)
• Shuffle and repeat modes
• Persistent mini player across screens
• Lyrics display support
• Background audio playback
• Smart track loading from popular artists

🔍 Search & Discovery

• Fast and responsive search
• Search suggestions and auto-complete
• Trending videos by region
• Category-based browsing
• Search history management

🎨 Themes & Customization

• 11+ Beautiful Color Themes:
  • Light (Default light mode)
  • Dark (Standard dark mode)
  • OLED Black (Pure black for AMOLED)
  • Ocean Blue (Deep sea vibes)
  • Forest Green (Nature-inspired)
  • Sunset Orange (Warm tones)
  • Purple Nebula (Cosmic purple)
  • Midnight Black (Dark with cyan)
  • Rose Gold (Elegant pink)
  • Arctic Ice (Cool cyan)
  • Crimson Red (Bold red)
  • And more...
• Smooth theme transitions
• Persistent theme selection

👤 User Interface

• Modern Material Design 3
• Smooth animations and transitions
• Shimmer loading effects
• Bottom navigation with smooth transitions
• Swipe gestures support
• Pull-to-refresh

📚 Library Management

• Watch history tracking
• Favorites/Bookmarks
• Playlists creation and management
• Continue watching section
• Watch later queue
• Shorts Bookmarks

🔒 Privacy & Data

• Clear watch history
• Clear search history
• Export data backup
• Import data restore
• No Google account required
• No ads or tracking

---

🏗️ Architecture

Flow follows clean architecture principles with a modular, component-based structure built entirely with Jetpack Compose and Kotlin.

Tech Stack

• Language: Kotlin 100%
• UI Framework: Jetpack Compose (Material Design 3)
• Architecture Pattern: MVVM (Model-View-ViewModel)
• Video Player: ExoPlayer (Media3)
• Data Extraction: NewPipeExtractor
• Async Operations: Kotlin Coroutines & StateFlow
• Local Storage: DataStore Preferences
• Image Loading: Coil
• Navigation: Jetpack Compose Navigation Components

Project Structure

The app is organized into clear, focused modules for maintainability and scalability

---

🚀 Getting Started

Prerequisites

• Android Studio Hedgehog or later
• JDK 17+
• Android SDK 24+

Installation

1. Clone the repository

   git clone https://github.com/A-EDev/Flow.git
   cd Flow

2. Open in Android Studio

   • Open Android Studio
   • Select "Open an existing project"
   • Navigate to the project directory

3. Sync Gradle

   • Android Studio will automatically sync Gradle
   • Wait for dependencies to download

4. Run the app

   • Connect an Android device or start an emulator
   • Click the "Run" button or press Shift+F10

---

📦 Releasing

Release instructions will be added soon.

---

💰 Support & Donations

If you find Flow useful and would like to support its development, you can donate via the following addresses:

• Bitcoin (BTC): bc1qgkmtxvzvysmtpfazqfls93jw6k4gjx0xmrtvn8
• USDT: 0xFbac6f464fec7fe458e31897a142ba45b305b7e (Ethereum Network)
• Ethereum (ETH): 0xFbac6f464fec7fe458e31897a142ba45b305b7e

Your support helps keep the project alive and motivates me to add more features!

---

🗺️ Roadmap

🔴 High Priority

• YouTube Algorithm Integration

  • Implement recommendation system
  • Personalized home feed
  • Related videos suggestions
  • Watch history-based recommendations
  • Trending videos integration
  • Improve algorithm accuracy
  • Implement Neural Engine that improves recommendations over time based on user behavior, it's privacy-focused and stores data locally.
  • User controls for algorithm tuning (reset, feedback)
  • Add interest metrics visualization for users to see their moods, interests and how they evolve over time. (Bubble chart, line graph, etc.)

• Shorts Support

  • Shorts feed UI
  • Vertical swipe navigation
  • Shorts player optimization
  • Shorts creation date/view count
  • Shorts bookmarking
  • Shorts Gesture Controls: Double-tap to like, Press and hold to speed

• Channel Screen

  • Complete channel page layout
  • Channel videos grid
  • Channel playlists
  • Channel Shorts
  • Channel about section
  • Subscribe functionality

• Remove Placeholder Data

  • Replace dummy trending data
  • Remove mock search results
  • Fix static playlist data
  • Real-time data fetching everywhere

🟡 Core Features

• Notification System

  • Push notifications setup
  • New video notifications
  • Download complete notifications
  • Playback controls in notification.(Music)
  • Notification settings

• Download Manager

  • Video download functionality
  • Download queue management
  • Quality selection for downloads
  • Downloaded videos library

• Comments System

  • Display video comments
  • Comment threads/replies
  • Sort comments (top/newest)
  • Comment engagement (likes display)
  • Comment posting (future)

• Social Features

  • Share videos functionality
  • Create shareable playlists
  • Export watch statistics
  • Follow favorite channels and artists

🟢 User Experience

• Search Enhancements

  • Search filters (date, duration, quality)
  • Advanced search operators
  • Voice search support

• Playback Features

  • Resume playback from last position
  • Watch together (sync viewing)
  • Live stream support
  • DVR controls for live streams

• Accessibility

  • Screen reader optimization
  • High contrast mode
  • Voice commands

🔵 Technical Improvements

• Performance Optimization

  • Implement pagination properly
  • Optimize image loading
  • Reduce memory usage
  • Background task optimization

• Testing

  • Unit tests coverage (80%+)
  • Integration tests
  • UI tests with Compose Testing
  • Performance benchmarks

• Architecture

  • Migrate to Hilt/Dagger for DI
  • Implement Room for local database
  • Add offline mode support
  • Implement proper error handling

🟣 Future Ideas

• Chromecast support
• Android TV version
• Tablet-optimized UI
• Wear OS companion app
• Community playlists
• Import YouTube subscriptions
• Sponsorblock integration
• Picture-in-Picture enhancements

---

🤝 Contributing

We welcome contributions from everyone! Please read our Contributing Guidelines for detailed information on how to contribute to Flow.

Ways to Contribute

• 🐛 Report bugs via Issues
• 💡 Suggest features or improvements
• 📚 Improve documentation
• 🚀 Submit pull requests

Quick Start

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

For more details, see CONTRIBUTING.md.

---

🙏 Acknowledgments

• NewPipeExtractor - Powerful library for YouTube data extraction
• MetroList - Inspiration for Hybrid InnerTube/NewPipeExtractor approach for Music fetching
• ExoPlayer - Professional-grade media player
• Jetpack Compose - Modern Android UI toolkit
• Material Design 3 - Beautiful design system by Google

---

📄 License

Flow is Free Software: You can use, study share and improve it at your will. It is distributed under the GNU General Public License v3 (GPLv3).

Copyright (c) 2025-2026 A-EDev

🚨 For Developers: This license requires that any project using Flow's source code (including the FlowNeuroEngine algorithm) must also be Open Source under the GPLv3 license. You may not use this code in a proprietary or closed-source application.

📞 Contact & Support

• Developer: A-EDev
• GitHub: @A-EDev
• Issues: Report a bug

---

🛠️ Troubleshooting

Installation Issues

"App not installed" or "Package conflict" error

If you see an error like "Installing the new update has conflict of package may be due to...signing key", it means the signature of the new version doesn't match the one currently installed on your device.

Solution:

1. Uninstall the existing version of the app.
2. Install the new version.

Note: This will clear your app data (settings, history, etc.). We are working on a backup/restore feature to mitigate this in the future.

---

🌟 Star History

If you find this project useful, please consider giving it a star! 🌟

---

📚 Additional Resources

• Code of Conduct
• Security Policy
• License

---

Made with ❤️ by A-EDev