[EN] 1.Getting Started

Add dependency

1. Make sure you have the jitpack repositories included in the build.gradle file in the root of your project.

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

2. Add a dependency in the build.gradle file of your app module

dependencies {
    implementation 'com.github.jrfeng.snow:player:1.2'
}

3. Request permission.

<!-- for start foreground service -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<!-- Android 14(API Level 34) -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

<!-- for play in the background -->
<uses-permission android:name="android.permission.WAKE_LOCK" />

<!-- Optional: for play local music -->
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
                 android:maxSdkVersion="32" />

<!-- Optional: for play network music -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Note: Android 6.0 (API level 23) need request android.permission.READ_EXTERNAL_STORAGE permission at runtime.

4. Create PlayerService

Create a class and let it extends the snow.player.PlayerService, and annotate it with @PersistenceId annotation. You don't need to override any methods of this class.

@PersistenceId("MyPlayerService")
public MyPlayerService extends PlayerService {
}

The @PersistenceId annotation is used to set a persistent ID for your PlayerService, which will be used for the persistence of the PlayerService state. If you do not use the @PersistenceId annotation to set the persistent ID, the persistent ID defaults to the full class name of your PlayerService (such as snow.demo.MyPlayerService). It is recommended to set a persistent ID for your PlayerService so that even if the PlayerService is renamed, the state will not be lost.

5. Register PlayerService on your AndroidManifest.xml file.

<service 
    android:name="snow.demo.MyPlayerService"
    android:exported="true"
    android:foregroundServiceType="mediaPlayback">
    <intent-filter>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>

<receiver android:name="androidx.media.session.MediaButtonReceiver" >
    <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
    </intent-filter>
</receiver>

Getting started

1. Connect to PlayerService.

// create a PlayerClient instance
PlayerClient playerClient = PlayerClient.newInstance(context, MyPlayerService.class);

// connect to MyPlayerService
playerClient.connect(new PlayerClient.OnConnectCallback() {
    @Override
    public void onConnected(boolean success) {
        // DEBUG
        Log.d("App", "connect: " + success);
    }
});

2. Create a Playlist.

Note: The URL of the MusicItem in the following example may be invalid. It is recommended that developers get the URL from other places and build the corresponding MusicItem object.

private Playlist createPlaylist() {
    MusicItem song1 = new MusicItem.Builder()
            .setTitle("太阳照常升起")
            .setArtist("久石让")
            .setAlbum("太阳照常升起 电影原声大碟")
            .setDuration(224013)
            .setUri("http://music.163.com/song/media/outer/url?id=441722")
            .setIconUri("http://p2.music.126.net/drqGdK7zgW7B7IFl4lWpoQ==/109951163369835547.jpg")
            .build();

    MusicItem song2 = new MusicItem.Builder()
            .setTitle("钢铁洪流进行曲")
            .setArtist("李旭昊")
            .setAlbum("国庆70周年阅兵BGM")
            .setDuration(186154)
            .setUri("http://music.163.com/song/media/outer/url?id=1394369908")
            .setIconUri("http://p2.music.126.net/KnC_YJjnRTNvCF82_2leCg==/109951164930615683.jpg")
            .build();

    MusicItem song3 = new MusicItem.Builder()
            .setTitle("国际歌-钢琴")
            .setArtist("曹伟健")
            .setAlbum("音迹")
            .setDuration(141369)
            .setUri("http://music.163.com/song/media/outer/url?id=1857796913")
            .build();

    MusicItem song4 = new MusicItem.Builder()
            .setTitle("我爱你中国[Forbid Seek]")
            .setDuration(136000)
            // cross-protocol redirects
            .setUri("https://music.163.com/song/media/outer/url?id=174451")
            .setIconUri("http://p2.music.126.net/x6pVwc6ysKZ9S01jYlYiAw==/97856534887060.jpg")
            // forbid seek
            .setForbidSeek(true)
            .build();

    return new Playlist.Builder()
            .append(song1)
            .append(song2)
            .append(song3)
            .append(song4)
            .build();
}

3. Set playlist and start playing music.

// create a Playlist instance.
Playlist playlist = createPlaylist();

// set playlist and start playing music
playerClient.setPlaylist(playlist, true);

---

End