Aperture

Finally, a Material 3 media player for Android TV!

---

✨ Features

• 🎨 Customisable Material 3 UI
• ⚡ Media3 Powered
• 🖼️ Name matching and asset detecting with TMDb

🚀 Getting Started

Important

• Organise your media under Movies/ and TV Shows/ folders in local or extended storage (Download, DCIM and Videos are also supported).
• Use clean file names and standard TV structures (e.g. Show Title/Season XX/SXXEXX.mp4).

Quick Install (Recommended)

Download the latest release .apk directly from the Releases tab and sideload it onto your Android TV device.

Tip

We recommend using Downloader by AFTVNews from the Google Play Store or the Amazon Appstore.

Or: Build From Source

1. Clone the repository:

   git clone https://github.com/XDanfr/Aperture.git

2. Open in Android Studio: Ensure your environment is configured to use JDK 17 or 21 (others are currently untested).

3. Add API Keys: local.properties needs a TMDB_API_KEY and an OPENSUBTITLES_API_KEY to function properly.

4. Sync & Deploy: Sync Gradle, build the project, and deploy it to your physical Android TV device or an emulator running API 27+.

Note

The repo is undergoing a pretty large rework on the front end to adopt Material 3 Expressive, and the back end is adopting more codec support. The latest commits may have some bugs.

📸 Screenshots

🗺️ Roadmap

Aperture is currently in ALPHA. Here is what is being tracked for future incremental updates:

Planned Features

• Transition to Material 3 Expressive: Very large rewrite planned for v0.5, using official Expressive tokens (this is complete and will arrive in the next update)
• Complete OpenSubtitles Integration
• Proper audio synchronisation: Forwards and backwards
• Default audio track selection: accessible in settings

Further Out

• Porting to PC: mobile will come afterwards
• Support for NAS types, Jellyfin and Plex
• Support for 3D TVs

🛠️ Tech Stack

• Language: Kotlin
• UI Framework: Jetpack Compose for TV
• Media Engine: Media3 / ExoPlayer
• Theming: Material 3
• Website Components: matraic/m3e

🤝 Contributing

Contributions are what make the open-source community such an amazing place! Want a feature or a bugfix? Pull requests are incredibly welcome.

• Issues: Open an issue if you discover a new bug or want to propose a fresh feature request.
• Pull Requests: Fork the project, create your branch, and submit a PR. Please make sure that your code aligns with the existing project style, unless you're going for a more M3E style as Material 3 transitions towards that look.

💬 FAQ

Q: How are mass local drives parsed?

A: The media architecture leverages standard Android Storage Access Framework processes to securely look up file spaces on attached storage hardware or local nodes.

Q: Was any AI used for this?

A: Gemini was used as a starter to build the baseline template. Some AI features (like autocomplete) were used to speed up development. However, all code is human-reviewed, manually structured, and the trickier bugs are tackled by hand! See [AI.md] for more.

---

💜 Sponsors

Aperture wouldn’t have active development without sponsors. Special thanks to them for keeping the app running :)

_{If you like Aperture, please consider supporting its development on GitHub Sponsors 💜}