Ease the development of media apps for Wear OS with the media toolkit

Published in

Android Developers

9 min readDec 15, 2022

Over the past two years, Wear OS usage has grown with the release of new devices. Media apps to play music, listen to podcasts, or follow guided workouts are now very popular with users.

In this blog post, you’ll learn how to bring your media app to Wear OS smartwatches with the help of the newly released Wear media toolkit and learn more about:

How the toolkit helps implement media use cases on Wear OS.
Media specific behaviors and unique UI challenges on the watch.
New Wear OS 3 features that can benefit a media app.
How to tailor your content for better performance on Wear OS.

Wear media toolkit

The Wear media toolkit is a set of libraries which accelerates the development of high-quality media apps for Wear OS. The toolkit is part of the Horologist project and provides a fully functional sample app that you can run to explore what you could build.

The toolkit uses the best-in-class libraries for media use cases, from an efficient and delightful UI implemented with Compose for Wear OS, to Media3 to implement the playback. Your app may have specific requirements, such as using a proprietary media player — in this case you can adopt the UI implementation from the toolkit while still relying on your existing player.

Media use cases

When you design your media app, start by considering two of the most important use cases:

Play downloaded content: download music or podcasts, so users can listen when they are working out without needing a network connection
Streaming: listen to music, podcasts, or a radio station, using any available network

Some users would also like to use Wear OS media apps to start and control media content on the phone: this is already possible by using the newly launched Assistant experience on the watch and Wear’s inbuilt media controls.

Solving for Wear-specific challenges

You may already be aware of media specific challenges when developing an Android mobile app. Watches have additional considerations like:

Inbuilt speakers are not designed for music playback
Smaller batteries and therefore limited power
Limited, or varying, network connectivity
Battery sensitivity to poor LTE signal

So, developing for the watch means taking additional things into consideration to give users the best experience:

Avoid playing media on watch speakers and use Bluetooth speakers/headsets
Enable audio offload
Avoid pinging the network connection unless absolutely necessary

Let’s dive into each of these problems and see how the media toolkit can help you to solve these challenges.

Avoid playing media on watch speakers

Most Wear OS devices have speakers. While watch speakers can be used for calls and guided activities, they don’t deliver the best experience for listening to media content as they are not designed for this purpose.

To give the best user experience, your app should make sure to play audio when Bluetooth headphones or speakers are connected to the watch.

The Media Toolkit makes this easy to do. It provides a specific Media3 extension that decorates the ExoPlayer instance and proactively stops accidental playback before it emits sound. This is implemented by checking if the current audio output is a Bluetooth device. If not, the toolkit launches the Bluetooth settings flow and allows the user to connect to their headset.

Check out the attemptToPlay function to see how this is implemented.

You can see how simple and logical this reusable library code is when layered on top of Media3 Player.

Enable audio offload

Audio offload allows audio processing to be offloaded from the CPU to a dedicated signal processor. This results in better performances and power saving, which is particularly important for apps on Wear OS.

The Media Toolkit provides support for audio offload via the AudioOffloadManager which configures and controls audio offload, enabling sleeping while your app is in the background and disabling while in the foreground.

Take a look at the sample app to see how AudioOffloadManager is enabled.

Please note that the following features are not currently supported by Audio offload:

Changing playback speed for podcast
Gapless
Volume Normalization

If you are not sure if audio offload is supported for a given audio format, use the AudioManager.isOffloadedPlaybackSupported() method.

For more information, see the Exoplayer docs.

Validate audio offload performance with Macrobenchmark

The Media Toolkit provides some benchmark tests that you can run to generate perfetto traces. To compare CPU performance when audio offload is enabled or disabled, run PlaybackBenchmark. This streams for 30 seconds. First it fetches for 10 seconds and after buffering, plays 25 seconds of audio.

See the following snapshots taken from ui.perfetto.dev for playback with audio offload disabled and enabled. These screenshots have been taken running PlaybackBenchmark on Pixel Watch connected to Pixel Buds.

Comparing the 2 images it’s easy to see that:

The CPU is not constantly working when audio offload is enabled.
The CPU frequency goes down (around 449 MHz) for longer periods when audio offload is enabled whereas when audio offload is disabled the CPU frequency oscillates more frequently towards higher values.

You can take a deeper look at what processes are running by running PlaybackBenchmark on Android Studio and importing the results on ui.perfetto.dev.

If you want to learn more about Macrobenchmark, read more on macrobenchmark overview.

Avoid network connections unless absolutely necessary

When you develop for Wear, you should expect users to have limited network connectivity. Many users leave their phone behind when they play media. And, listening to downloaded content brings significant battery savings for the user even if they do have an available network connection.

The toolkit makes it simple to optimize media downloads. It provides a MediaDownloadService implemented using Media3’s DownloadManager and Androidx Work Manager to schedule downloads. Media3 starts all the right notifications and foreground services, and the sample app code configures the Work Manager to run the downloads when Wi-Fi connection is available to ensure better performance. This is achieved by using the NetworkAwareness module which allows developers to map network operations with network type.

To summarize, by using the MediaDownloadService you can ensure that users have reliable, performant downloads so they can play media on the go.

UI Design

The Wear media toolkit provides a UI module to help build UI screens for your app.

The UI module uses Compose for Wear OS which brings many components tailored to the watch and ensures your app adheres to Material design. It also provides a delightful developer experience with Android Studio integration such as previews and animation tools. Compose for Wear OS and the toolkit come with built-in accessibility and translations across all screens.

You can easily use and adapt the Wear media toolkit screens to the specific style of your app. The screens follow core design principles, showcased by the media sample app:

Apps should be organized using 2 swipeable screens: Player and Library
The Player screen gives quick access to important playback actions. The Player screen should have a 5 button layout. This ensures our minimum tap targets are met and users can control the media easily whilst on the go.
The Library screen allows users to find media to play. Keep the content hierarchy as flat as possible in the Library screen to reduce complexity.

Upon tapping on content from the Library, users should be presented with entity pages, such a Playlist. An entity page gives users more information about what a media item contains. It also contains important user actions like manual download and play / shuffle.

Adapt actions depending on the type of content: if you have a podcast you may want to allow the user to fast forward 30 seconds instead of skipping to next.
You can customize the icons and font in your media app, but the minimum font size is 12dp. For primary content, such as song name and artist name, the font size should be at least 14dp.
For devices with an RSB (rotating side button) or bezel, enhance the user experience by using this interaction to change the volume or scroll through content.

By running the sample app, you can immediately see how the toolkit helps you build the app screens while following the principles listed above.

Ongoing Activity

An Ongoing Activity is a new feature in Wear OS 3 that allows an Ongoing Notification to appear on additional surfaces within the Wear OS user interface.

This allows users to stay more engaged with long running activities. Fitness and media apps benefit from this feature. An Ongoing Activity shows up on the watchface and on recents apps.

Design your app to open the player screen when the Ongoing Activity notification is tapped. This allows the user to quickly perform an action, such as pausing a song while it is playing.

Wear OS automatically takes care of creating Ongoing Activities for media apps if you use Media 3; you just need to provide an intent for opening the app. This is why the sample app simply provides a deep link to the Player Screen to get the Ongoing Activity to open the Player screen.

Performance considerations

A big part of ensuring your app has good performance comes down to optimizing playback for streaming and downloaded music, and the download operation.

The Wear media toolkit helps to build the foundation of a performant app, such as providing the Network Awareness module to choose the better connection for a specific operation, but there are specific app choices that you need to consider to make an app perform well on the watch.

Considerations for streaming:

Optimize the content by choosing a low bitrate for streaming, such as 48kbps and codecs such as AAC and MP3.
Optimize the prefetch strategy for images and tracks to ensure continuing playback when you lose connection temporarily. Avoid the experience of a user entering an area with weak and no signal, listening to streamed content, and music abruptly stopping because network connection is lost.
Test your app in all network configurations: Wi-Fi, LTE, watch connected to phone via Bluetooth. Also test what happens when the watch switches between networks.

Considerations for downloading content:

Using WiFi is much better than using a Bluetooth connection to download media onto a watch. If the user is on a LTE plan, it’s a good idea to check if the user is aware that the download operation will be using LTE data, which could potentially become an expensive operation.

Considerations for playback (streamed and downloaded music):

Users listening to media content on a watch should not be experiencing excessive battery drain: even if a network is available, limit the traffic by sending less frequent pings to the server and choose a lower artwork image resolution.

Wrap-up

Build your media app on Wear OS by using the Wear media toolkit. The toolkit has been designed to make development easier while ensuring media specific behaviors are implemented and Wear media design principles are adopted.

Checkout our Android Developer Summit 2022 talk, Building media apps on Wear OS, for a great overview on this topic.

d.android.com/wear is the best place to check the latest guidance related to Wear OS development. And don’t forget to provide feedback to the Horologist project which hosts the Wear media toolkit.