Skip to content

Commit

Permalink
Update docs (google#2232)
Browse files Browse the repository at this point in the history
* Uses Horologit button

* Uses Horologist AlertDialog, removes button

* Moves logs into its own docs, remove Playback Rules
  • Loading branch information
kul3r4 authored May 16, 2024
1 parent 13f5958 commit b469528
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 66 deletions.
3 changes: 2 additions & 1 deletion docs/media-sample.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ uses [Media3](https://developer.android.com/jetpack/androidx/releases/media3).

The app showcases the implementation of the following features:

- Media playback, restricted to paired Bluetooth devices
- Media playback, restricted to paired Bluetooth devices.
This is achieved by calling [`setSuppressPlaybackOnUnsuitableOutput`](https://developer.android.com/reference/androidx/media3/exoplayer/ExoPlayer.Builder#setSuppressPlaybackOnUnsuitableOutput(boolean)) method on the `Exoplayer` instance.
- Launch of Bluetooth settings to connect devices for media playback
- Volume control
- Radial background based on media artwork color palette
Expand Down
65 changes: 0 additions & 65 deletions docs/media3-backend.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,51 +15,6 @@ engine for Wear OS media apps.
All functionality is demonstrated in the `media-sample` app, and as such is not described here
with extensive code samples.

### Bluetooth Headphone Connections

Any extended playback such as music, podcasts, or radio should only use a connected bluetooth
speaker. See https://developer.android.com/training/wearables/principles#bluetooh-headphones for
principles applying to Media and Wear OS apps generally.

When not connected, the default Watch Speaker will be used and so this must be actively
avoided.

Horologist provides the `PlaybackRules` abstraction that allows you to intercept playback requests
through your UI, a system media Tile, pressing a bluetooth headphone, or other services such as
assistant.

```kotlin
public object Normal : PlaybackRules {
/**
* Can the given item be played with it's given state.
*/
override suspend fun canPlayItem(mediaItem: MediaItem): Boolean = true

/**
* Can Media be played with the given audio target.
*/
override fun canPlayWithOutput(audioOutput: AudioOutput): Boolean =
audioOutput is AudioOutput.BluetoothHeadset
}
```

The `WearConfiguredPlayer` wraps the ExoPlayer to avoid starting playback and also pause immediately
if the headset becomes disconnected. It will prompt the user to connect a headset at this point.

The `AudioOutputSelector` and default implementation `BluetoothSettingsOutputSelector` are used
to prompt the user to connect a Bluetooth headset and then continue playback once connected.

```kotlin
public interface AudioOutputSelector {
/**
* Change from the current audio output, according to some sensible logic,
* and return when either the user has selected a new audio output or returning null
* if timed out.
*/
public suspend fun selectNewOutput(currentAudioOutput: AudioOutput): AudioOutput?
}
```

### Audio Offload

In line with https://exoplayer.dev/battery-consumption.html#audio-playback, Audio Offload
Expand All @@ -70,26 +25,6 @@ Audio Underruns.
The `AudioOffloadManager` configures and controls Audio Offload, enabling sleeping while your app
is in the background and disabling while in the foreground.

### Logging

The `media3-backend` module interacts with `ExoPlayer` instance, but many events may be required
for error handling, logging or metrics. Your can register your own `Player.Listener` with the
`ExoPlayer` instance, but to receive generally useful events you can implement `ErrorReporter`
to receive events and report with Android `Log` or write to a database.

Other things in the Horologist media libs will report events, and they all consistently use
`ErrorReporter` to allow you to understand all activity in your app.

```kotlin
public interface ErrorReporter {
public fun logMessage(
message: String,
category: Category = Category.Unknown,
level: Level = Level.Info
)
}
```

## Download

```groovy
Expand Down
38 changes: 38 additions & 0 deletions docs/media3-logging.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Wear Media3 Logging library

[![Maven Central](https://img.shields.io/maven-central/v/com.google.android.horologist/horologist-media3-logging)](https://search.maven.org/search?q=g:com.google.android.horologist)

## Features
The `media3-logging` module implements logging of events.

### Logging

The `media3-logging` module interacts with `ExoPlayer` instance, but many events may be required
for error handling, logging or metrics. Your can register your own `Player.Listener` with the
`ExoPlayer` instance, but to receive generally useful events you can implement `ErrorReporter`
to receive events and report with Android `Log` or write to a database.

Other things in the Horologist media libs will report events, and they all consistently use
`ErrorReporter` to allow you to understand all activity in your app.

```kotlin
public interface ErrorReporter {
public fun logMessage(
message: String,
category: Category = Category.Unknown,
level: Level = Level.Info
)
}
```

## Download

```groovy
repositories {
mavenCentral()
}
dependencies {
implementation "com.google.android.horologist:horologist-media3-logging:<version>"
}
```

0 comments on commit b469528

Please sign in to comment.