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).

Updating from 0.4.2-alpha or earlier

0.5 uses a new signing key and the package name cc.xdan.aperture. Install and open the new APK. If the old app is detected, Aperture will guide you through uninstalling it, then rebuilding your library. While scanning, you can choose a theme and customise Ambient mode. When ready, choose Get started or Learn Aperture. Settings, My List and watch progress start fresh; your media files remain on your device.

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:

Tester feedback priorities

Address these before expanding the shared focus-morph experiment:

• Large-library browsing performance: Investigate slow first entry and lag on the Movies page with libraries of 900+ movies. Measure database work, UI preparation and artwork loading before choosing a fix; consider retaining prepared library data, paging and bounded artwork loading/caching so opening a page does not require preparing the entire library. Check first entry, reopening and scrolling on Android TV hardware.
• Onboarding overhaul: Rework first-run setup, library selection and scan/progress feedback into a clearer flow that is comfortable to navigate with a remote.
• Compact, adaptive sidebar: Reduce the expanded sidebar width and excess gap before page content while preserving the original branding and readable labels. Allow the focus pill to grow and shrink horizontally with its destination rather than leaving a long fixed-width chip; coordinate this with the shared focus morph where appropriate, without shifting entries vertically.
• Subtitle QuickMenu layout: Fix subtitle option labels sitting against the top/left edges of rounded cards, including clipping of “Off”. Give the track options consistent padding and alignment, and keep Sync/Customise actions readable and comfortably spaced when focused on a TV.

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: (Complete in v0.5)
• Proper audio synchronisation: Forwards and backwards
• Default audio track selection: accessible in settings

Playback and TV interaction

• Keep the sidebar closed behind playback menus: Returning from playback and closing a play menu should preserve the selected item without opening the sidebar in the background.
• Spotlight show continuation: Open the current or next episode with the season and episode selector, matching Continue Watching.
• Show continuation throughout the library: My List, Search, TV Shows and other grouped show cards should open the current or next episode. Rewatching an earlier episode becomes the latest priority and continues from there.
• Next episode popup: In the final 10 seconds of an episode, show a focused preview card with the next episode's season, number, title and existing episode thumbnail, plus a “Playing in X” countdown. Selecting the card plays it immediately. An X below dismisses the popup and disables automatic continuation for that episode; when the video ends, close the player.
• Consistent Continue Watching progress color: Focusing a card should preserve the progress bar's color.
• Animated sidebar focus: Move the focus highlight smoothly between destinations using Aperture's motion tokens, with text color following the highlight and no replay of the previous hover on reopening.
• Sidebar brand reveal: Keep the original Aperture icon visible, centered with the entry icons. Reveal the original wordmark alongside the entry labels when the sidebar opens, keeping the collapsed rail compact.
• Animated idle Spotlight transitions: Give automatic title changes the same motion as remote navigation, with a Google TV inspired wipe between banners.
• Simplify visible settings: Hide the Rounded Spotlight and Classic Player Controls switches while retaining their implementations and stored preferences.
• Experimental options section: Provide a future home for alternate Spotlight layouts, classic controls, a sidebar-brand visibility preference and similar optional features.

Further Out

• Resizable banners and title logos: Support adjustable banner presentation and show/movie logos, including white variants where appropriate.
• 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 💜}