SwiftUI Emby Client: A Universal Open Source Project

Hey guys! I'm super excited to share my personal project with you all – a universal Emby Media Server client built with SwiftUI. This has been a labor of love, and I'm thrilled to finally talk about it. The app supports macOS, iOS, and tvOS, and I've even released it under the MIT license, meaning it's completely free and open-source! In this article, I’ll walk you through the journey of building this client, the challenges I faced, the technologies I used, and why I chose to make it a universal app. So, buckle up and let’s dive in!

Why Emby and Why a New Client?

Let's kick things off by discussing why I chose Emby and why I felt the need to create a new client. For those unfamiliar, Emby is a fantastic media server that lets you organize and stream your personal media collection—movies, TV shows, music, and photos—across various devices. I've been an Emby user for years, and I absolutely love its features: live TV, DVR, parental controls, and the ability to customize the interface. However, while Emby has official clients for different platforms, I always felt there was room for improvement, especially in terms of user experience and native integration with Apple's ecosystem.

The existing Emby clients, while functional, often felt a bit clunky and not quite as polished as native macOS, iOS, and tvOS apps. I wanted a client that felt right at home on each platform, taking full advantage of Apple's technologies and design paradigms. This meant leveraging SwiftUI for a modern, declarative UI, and ensuring seamless integration with features like AirPlay, iCloud, and the Apple TV remote. Furthermore, I had some specific ideas about how to improve media browsing, playback controls, and overall navigation. I envisioned a client that was not only feature-rich but also a joy to use. This vision fueled my desire to embark on this project and create something truly special.

My primary goal was to create a client that was both visually appealing and incredibly intuitive. I wanted users to be able to easily navigate their media libraries, discover new content, and enjoy a seamless playback experience. This meant paying close attention to details like typography, spacing, and animations. I also wanted to ensure that the app was performant and responsive, even when dealing with large media libraries. This required careful attention to data fetching, caching, and UI rendering. Ultimately, my aim was to build an Emby client that would become the go-to choice for Apple users who value both functionality and elegance. The decision to make it a universal app was driven by the desire to provide a consistent experience across all Apple devices. Whether you're watching a movie on your Mac, catching up on a TV show on your iPad, or enjoying a family movie night on your Apple TV, the experience should feel familiar and seamless. This was a significant undertaking, but I believed it was essential to creating a truly exceptional Emby client.

SwiftUI: The Perfect Choice for a Universal App

Speaking of SwiftUI, let's talk about why I chose it for this project. SwiftUI, Apple's modern UI framework, is a game-changer for app development. It allows you to build user interfaces declaratively, meaning you describe what you want the UI to look like, and SwiftUI takes care of how to render it. This approach is not only more efficient but also makes it easier to create consistent UIs across different platforms. For a universal app targeting macOS, iOS, and tvOS, SwiftUI was the perfect choice.

One of the biggest advantages of SwiftUI is its cross-platform compatibility. With a single codebase, I could build the core UI and logic of the Emby client and then adapt it to each platform's specific needs. This saved me a tremendous amount of time and effort compared to using separate frameworks like UIKit for iOS and AppKit for macOS. SwiftUI's declarative nature also made it easier to manage the UI's state and handle user interactions. The framework's built-in data binding and state management features simplified the process of keeping the UI in sync with the underlying data. This was particularly crucial for a media client, where the UI needs to respond dynamically to changes in playback status, media metadata, and user preferences.

Furthermore, SwiftUI's modern design language aligns perfectly with Apple's aesthetic guidelines. The framework provides a rich set of built-in views and controls that are both visually appealing and highly customizable. This allowed me to create a user interface that felt native and intuitive on each platform. I could easily adapt the layout, typography, and color scheme to match the look and feel of macOS, iOS, and tvOS. In addition to its cross-platform capabilities and modern design, SwiftUI also offers excellent performance. The framework is highly optimized for rendering complex UIs, and it leverages hardware acceleration to ensure smooth animations and transitions. This was essential for creating a fluid and responsive media client that could handle high-resolution video playback and large media libraries. Overall, SwiftUI proved to be an invaluable tool for building my universal Emby client. Its declarative nature, cross-platform compatibility, and performance made it the ideal choice for this project.

Building the Core Features: Browsing, Playback, and More

Now, let’s delve into the heart of the project: the core features. Building a media client involves several key components: media browsing, playback, user authentication, and settings. Each of these areas presented its own set of challenges and required careful planning and implementation. The first step was to tackle media browsing. I needed to create a UI that allowed users to easily navigate their Emby libraries, browse movies, TV shows, music, and other content. This involved fetching data from the Emby server, parsing the responses, and displaying the media items in a visually appealing and organized manner.

For media browsing, I implemented a hierarchical navigation system that mirrored the structure of the Emby library. Users could browse by library type (movies, TV shows, music), then drill down into specific folders, genres, or playlists. I used SwiftUI's List and NavigationView components to create a familiar and intuitive browsing experience. Each media item was displayed with its title, artwork, and a brief description. I also implemented search functionality, allowing users to quickly find specific items within their libraries. Playback was another critical feature that required careful attention. I wanted to ensure a smooth and reliable playback experience across all platforms. This involved handling various media formats, implementing playback controls (play, pause, seek, volume), and supporting features like AirPlay and casting. I used Apple's AVKit framework for media playback, which provides a robust set of APIs for handling audio and video content. I created custom playback controls using SwiftUI, allowing users to easily control the playback experience. I also implemented support for subtitles and audio track selection, giving users more control over their viewing experience.

User authentication was another essential aspect of the project. I needed to implement a secure and reliable way for users to connect to their Emby servers. This involved handling user credentials, authenticating against the Emby API, and storing authentication tokens securely. I used the Emby API's built-in authentication mechanisms and implemented a secure storage solution for user credentials. I also implemented support for multiple Emby servers, allowing users to connect to multiple libraries from within the app. Finally, I implemented a settings screen that allowed users to customize the app's behavior. This included options for configuring the Emby server connection, setting playback preferences, and managing user accounts. I used SwiftUI's Form component to create a clean and organized settings interface. I also implemented support for iCloud sync, allowing users to synchronize their settings across multiple devices. Building these core features was a significant undertaking, but it was also incredibly rewarding. Seeing the Emby client come to life and being able to browse and play my media library on all my Apple devices was a huge accomplishment.

The Challenges and Solutions Along the Way

Of course, no project is without its challenges, and this one was no exception. Building a universal app with SwiftUI, while powerful, also presented some unique hurdles. I encountered issues with platform-specific UI adaptations, data management, and performance optimization. One of the first challenges I faced was adapting the UI to fit the different screen sizes and input methods of macOS, iOS, and tvOS. SwiftUI's layout system is flexible, but it still required careful consideration to ensure that the UI looked good and functioned well on all platforms.

On macOS, I needed to design a UI that was optimized for mouse and keyboard input, while on iOS and tvOS, I needed to account for touch and remote control interactions. I used SwiftUI's #if os() directives to conditionally apply platform-specific UI modifications. For example, I used different navigation styles on macOS and iOS to match the platform's conventions. I also used different button styles and spacing to optimize for touch and remote control input. Data management was another area that required careful planning. The Emby API returns a large amount of data, and I needed to ensure that the app could handle it efficiently. I used a combination of caching, data paging, and background processing to minimize the impact on performance. I implemented a local cache to store frequently accessed data, such as media metadata and artwork. This reduced the number of requests to the Emby server and improved the app's responsiveness. I also used data paging to load media items in batches, rather than loading the entire library at once. This prevented the app from becoming sluggish when browsing large libraries. Background processing was used to perform tasks that could potentially block the main thread, such as downloading artwork and transcoding media. This ensured that the UI remained responsive even when the app was performing intensive operations.

Performance optimization was a constant concern throughout the project. SwiftUI is generally performant, but there are still opportunities to improve performance, especially when dealing with complex UIs and large datasets. I used Instruments, Apple's performance profiling tool, to identify bottlenecks and optimize the app's performance. I focused on reducing the number of UI updates, minimizing memory allocations, and optimizing image loading. I also used SwiftUI's LazyVGrid and LazyHStack components to defer the loading of UI elements until they were visible on screen. This significantly improved the app's startup time and scrolling performance. Overcoming these challenges required a combination of technical expertise, creative problem-solving, and a lot of patience. But in the end, I was able to build a universal Emby client that is both performant and visually appealing across all platforms.

Open Source and the MIT License

One of the most important decisions I made early on was to release this project as open source under the MIT license. I believe in the power of open source software and the benefits of collaboration. By making the code freely available, I hope to encourage others to contribute, learn, and build upon my work. The MIT license is a permissive license that allows anyone to use, modify, and distribute the software, even for commercial purposes. This gives users the freedom to adapt the client to their specific needs and to contribute improvements back to the community.

My goal in open-sourcing this project is to foster a community of developers and users who are passionate about Emby and SwiftUI. I hope that others will find the code useful as a learning resource, and I welcome contributions in the form of bug fixes, feature enhancements, and new ideas. I also believe that open source software is more transparent and trustworthy. By making the code public, I allow anyone to inspect it and verify that it is secure and does not contain any malicious code. This is particularly important for a media client, which handles sensitive user data such as login credentials and media library information. I have set up a GitHub repository for the project, where you can find the source code, documentation, and issue tracker. I encourage you to check it out, explore the code, and contribute your ideas and feedback. I am committed to maintaining this project and providing ongoing support to the community. I believe that together, we can build an even better Emby client that serves the needs of all users.

Future Plans and How You Can Contribute

So, what’s next for this project? I have a long list of features and improvements that I’d like to implement in the future. I'm planning to add support for more advanced Emby features, such as live TV and DVR. I also want to improve the playback experience by adding support for more media formats and playback options. Additionally, I'm working on enhancing the user interface and making it even more customizable. But I can’t do it alone! This is where you come in. As an open-source project, your contributions are invaluable. Whether you're a seasoned developer or just starting out, there are many ways you can contribute to this project.

If you’re a developer, you can help by fixing bugs, implementing new features, or improving the code's performance. If you’re not a developer, you can still contribute by providing feedback, reporting issues, or helping with documentation. Every contribution, no matter how small, helps make the project better. I encourage you to check out the GitHub repository, explore the code, and submit pull requests with your changes. If you have an idea for a new feature or improvement, please open an issue and let's discuss it. I'm always open to new ideas and suggestions. I also plan to create a more detailed roadmap for the project, outlining the features and improvements that I'm planning to implement in the future. This will help contributors understand the project's direction and prioritize their efforts. I'm excited about the future of this project and the potential it has to become a truly exceptional Emby client. With your help, we can make it happen. Thank you for your interest and support!