🎵 ForgeMusic

A listening room for your music and videos on Android.

ForgeMusic is a Flutter-powered Android media player designed to bring local music, video playback, and YouTube listening together in one place. Enjoy media stored on your device, manage music metadata, and keep playback controls accessible through Android notifications.

✨ Features

• 🎧 Local Music Playback — Listen to music stored on your Android device.
• 🎬 Video Playback — Enjoy video content alongside your music library.
• ▶️ YouTube Listening — Access YouTube playback for personal listening.
• 📚 Media Library Scanning — Scan your device for supported music and video files.
• 🏷️ Metadata Editing — Edit supported audio file tags, including files outside the app directory when the required Android permission is granted.
• 🔔 Notification Playback Controls — Access playback controls from the Android notification shade.
• 📱 Android-Focused Experience — Built with Flutter for Android devices.

🛠️ Built With

Technology	Purpose
Flutter	Cross-platform application framework
Dart	Application programming language
Android SDK	Android platform integration
YouTube	Online media playback

🚀 Getting Started

Follow these instructions to run ForgeMusic locally.

Prerequisites

Make sure you have installed:

• Flutter SDK
• Dart SDK (included with Flutter)
• Android Studio or another supported development environment
• Android SDK and an Android emulator or physical Android device
• Git

Verify your Flutter installation:

flutter doctor

Installation

1. Clone the repository

git clone https://github.com/Ibrahist/Forgemusic.git

2. Navigate to the project directory

cd Forgemusic

3. Install dependencies

flutter pub get

4. Run the application

Connect an Android device or start an emulator, then run:

flutter run

Build an APK

To generate a debug APK for testing:

flutter build apk --debug

The generated APK is typically available at:

build/app/outputs/flutter-apk/app-debug.apk

For a release build, run:

flutter build apk --release

Configure any required Android signing settings before distributing a production release.

📂 Project Structure

Forgemusic/
├── android/               # Android platform configuration
├── assets/
│   └── fonts/             # Application fonts
├── lib/                   # Main Flutter application source
├── test/                  # Application tests
├── .gitignore             # Git ignore rules
├── .metadata              # Flutter project metadata
├── analysis_options.yaml  # Dart analysis configuration
├── pubspec.yaml            # Dependencies and project configuration
├── pubspec.lock            # Resolved dependency versions
└── README.md               # Project documentation

🔐 Permissions

ForgeMusic may request Android permissions to support its media features.

• Media access: Allows the app to scan and play supported local media.
• Notification access: Supports playback controls displayed in the notification shade.
• All-files access: Required for tag editing on supported files outside the application's own directory. Enable this permission through Android Settings when needed.

Grant only the permissions required for the features you use.

🧪 Testing

Run the Flutter test suite with:

flutter test

Check the project for Dart and Flutter issues with:

flutter analyze

⚠️ Responsible Use

• YouTube playback is intended for personal listening.
• Respect copyright laws and YouTube's applicable Terms of Service.
• Make sure you have permission to access, modify, or use media files.
• Downloaded media remains on the device, as described by the project.

🗺️ Roadmap

Potential areas for future development include:

• Improve music library organization and browsing.
• Enhance playback controls and user experience.
• Expand media metadata management.
• Improve application testing and reliability.
• Refine the Android user interface.

Roadmap items are suggestions for future development, not a statement that these features are currently implemented.

🤝 Contributing

Contributions, suggestions, and bug reports are welcome.

1. Fork the repository.

2. Create a feature branch:

   git checkout -b feature/your-feature

3. Commit your changes:

   git commit -m "Add your feature"

4. Push your branch:

   git push origin feature/your-feature

5. Open a pull request describing your changes.

For significant changes, consider opening an issue first to discuss the proposed improvement.

🐛 Reporting Issues

If you encounter a bug or have a feature request, visit the GitHub Issues page.

Include relevant error messages, reproduction steps, and your Android and Flutter versions where possible.

👨‍💻 Author

Ibrahist

• GitHub: @Ibrahist
• Project: ForgeMusic

📄 License

This project is licensed under the GNU General Public License v3.0 (GPL v3.0).

See the LICENSE file for the full license text.

📜 GNU General Public License v3.0 (GPL v3.0) — Click to view details

Overview

ForgeMusic is free and open-source software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Permissions	Conditions	Limitations
✅ Commercial use	ℹ️ Disclose source	❌ Liability
✅ Distribution	ℹ️ License and copyright notice	❌ Warranty
✅ Modification	ℹ️ State changes
✅ Patent use	ℹ️ Same license (GPL-3.0)
✅ Private use