UPnP Toaster API

Table of contents:

Getting started

Upnp API is a library project that gives your app ability to use UPNP networking protocol and cast media files via Toaster - full featured UPnP Media Player.

Download the code to get started. Add project to you workspace and include UPnPApi as a library.

 

Download Toaster API sample project from github.

Usage

After including the library into your application you have access to class PublicApi. It is the main point of the library. To cast media files you must stick to particular cycle of UPnP streaming:

1. Create PublicApi object and register your application

It is the main interface between your app and Toaster.

PublicApi mApi = new PublicApi(this);
mApi.actionRegisterApplication(this, REGISTER_APP_REQ, new OnActionCompleteListener() {

			@Override
			public void onActionComplete(long reqCode, int statusCode, String description) {
				Toast.makeText(ActivityUpnpTest.this, description, Toast.LENGTH_SHORT).show();
			}
		});

2. Set Playback Listener

Create Playback Listener and add it to PublicApi using setPlaybackListener method. Listener gives you callbacks about position, state, volume changes and informs you when player is disconnected.

mApi.setPlaybackListener(new PublicApi.PlaybackListener() {
			
			@Override
			public void onVolumeChanged(Long reqCode, int value) {
				
			}
			
			@Override
			public void onStateChanged(int stateChanged) {
				
			}
			
			@Override
			public void onPositionChanged(long position, long mediaDuration) {
				
			}
			
			@Override
			public void onPlayerDisconnected(int disconnectedCode, String description) {
				
			}
		});
											

3. Select Renderer

To select renderer use the selectRenderer method. It starts new activity that looks for local UPnP devices and gives the user ability to select one of them. To receive chosen device use parseSelectRendererResult inside your activities onActivityResult method. Chosen device is an instance of DeviceResult object. After getting it you should check reqStatusCode for errors. Check error codes in Code table.

mApi.selectRenderer(this, reqCode);
	@Override
	protected void onActivityResult(int requestCode, int resultCode, Intent data) {
		DeviceResult device = PublicApi.parseSelectRendererResult(data);
		super.onActivityResult(requestCode, resultCode, data);
	} 

4. Cast media files and control playback

Use many, many actions from Public Api to control playback.

		String trackFilepath = "/storage/sdcard0/Music/sample.mp3";
		String title = "Sample title";
		String album = "Sample album";
		String artist = "Sample artist";
		long duration = 224031;
		long size = 5380850;
		long bitrate = 88200;
		String albumArtfilepath = "/storage/sdcard0/Music/sample.png";
		
		mApi.actionPlayItem((Context) MainActivity.this, PLAY_ITEM_REQ, trackFilepath, title, album, artist, 
		albumArtfilepath, duration, size, bitrate, false, new OnActionCompleteListener() {

					@Override
					public void onActionComplete(long reqCode, int statusCode, String description) {
						if (statusCode == PublicApi.INFO_OK) {
							Toast.makeText(ActivityUpnpTest.this, "Playing: " + title, Toast.LENGTH_SHORT).show();
						}
					}

				});
int volumeLevel = 80;
mApi.actionSetVolume(this, SET_VOLUME_REQ, volumeLevel, new PublicApi.OnActionCompleteListener() {
			
			@Override
			public void onActionComplete(long reqCode, int statusCode, String description) {
				Toast.makeText(ActivityUpnpTest.this, "Volume changed", Toast.LENGTH_SHORT).show();
			}
		});

5. Unregister your application after finished work

Use actionUnregisterApplication to unregister your application.

PublicApi.actionUnregisterApplication(this, UNREGISTER_APP_REQ);

6. Destroy PublicApi

Use destroy method inside your Activity onDestroy method.

@Override
protected void onDestroy() {
	mApi.destroy(this);
	super.onDestroy();
}
										

Samples

Download sample project from github or bitbucket.

Reference

Player -> UPNP Communication

Broadcasts

Action nameAction descriptionArgument nameArgument typeArgument descriptionRequired
com.n7mobile.upnpplayer.ACTION_REGISTER_APPLICATION Registers application and unregisters any other clients. Required to use other methods. CLIENT_PACKAGE String Application package to register
REQ_CODE long Request identificator
com.n7mobile.upnpplayer.ACTION_UNREGISTER_APPLICATION Unregisters the application and lets UPNP service die CLIENT_PACKAGE String Application package to unregister
REQ_CODE long Request identificator
com.n7mobile.upnpplayer.ACTION_SET_RENDERER Sets the renderer with the given UDN identificator. REQ_CODE long Request identificator
CLIENT_PACKAGE String Registered application package
DEVICE_UDN String Device identificator
com.n7mobile.upnpplayer.ACTION_AV_PLAY Resumes playing or starts playing new media file. REQ_CODE long Request identificator
com.n7mobile.upnpplayer.ACTION_AV_PAUSE Pauses playback. REQ_CODE long Request identificator
CLIENT_PACKAGE String Registered application package
com.n7mobile.upnpplayer.ACTION_AV_STOP Stops playback. REQ_CODE long Request identificator
CLIENT_PACKAGE String Registered application package
com.n7mobile.upnpplayer.ACTION_SET_VOLUME Sets the volume with 0-100 numeric value REQ_CODE long Request identificator
CLIENT_PACKAGE String Registered application package
VOLUME int Volume value from 0 to 100
com.n7mobile.upnpplayer.ACTION_SET_MUTE Mute the renderer. REQ_CODE long Request identificator
MUTE boolean Mute
com.n7mobile.upnpplayer.ACTION_RISE_VOLUME Adjust renderer volume in terms of max volume level. For example 0.1 will turn volume up by 10% maximum volume. REQ_CODE long Request identificator
CLIENT_PACKAGE String Registered application package
VOLUME_LVL float Volume turn up value from 0 to 1.0
com.n7mobile.upnpplayer.ACTION_SEEK Sets the playback position in currently playing file. REQ_CODE long Request identificator
CLIENT_PACKAGE String Registered application package
SEEK_MILIS long Position in milliseconds
com.n7mobile.upnpplayer.ACTION_PLAY_ITEM Sets the file to play. REQ_CODE long Request identificator
CLIENT_PACKAGE String Registered application package
ITEM_PATH String Filepath
ITEM_TITLE String Title  
ITEM_ALBUM String Album name  
ITEM_CREATOR String Creator/Composer  
ITEM_COVERART_PATH String Albumart filepath  
ITEM_DURATION long Duration  
ITEM_MIMETYPE String Media type e.g. (audio/mp3)
ITEM_SIZE long File size  
ITEM_BITRATE long Bitrate  
com.n7mobile.upnpplayer.ACTION_GET_VOLUME Sends request for current volume level. REQ_CODE long Request identificator
CLIENT_PACKAGE String Registered application package

Activity.startForResult

Action nameAction descriptionArgument nameArgument typeArgument descriptionRequired
com.n7mobile.upnpplayer.ACTIVITY_SELECT_RENDERER Starts new activity with renderer chooser. Intent extra values
CLIENT_PACKAGE String Registered application package
DEVICE_UDN String Device identificator  
On Activity Result values
DEVICE_UDN String Device identificator  
DEVICE_NAME String Device name  
DEVICE_MANUFACTURER String Device manufacturer  
REQ_STATUS_CODE int Request status code  
INFO_DESCRIPTION String    

UPNP - > Player Communication

Action nameAction descriptionArgument nameArgument typeArgument description
com.n7mobile.upnpplayer.RECEIVE_POSITION_CHANGE Returns current playback time. POSITION long Current playback position in milliseconds
MEDIA_DURATION long Media file duration
com.n7mobile.upnpplayer.RECEIVE_STATE_CHANGE Returns player state change info. STATE_CODE int State code
com.n7mobile.upnpplayer.RECEIVE_ERROR Returns error info. ERROR_CODE int Error code
ERROR_DESCRIPTION String Error description
com.n7mobile.upnpplayer.RESPONSE_INFO Returns status and description of action execution identified by REQ_CODE. REQ_CODE long Request identificator
REQ_STATUS_CODE long Request status code
INFO_DESCRIPTION String Status description
com.n7mobile.upnpplayer.RECEIVE_DEVICE_DISCONNECTED Informs about losing internet connection. DISCONNECT_CODE int Disconnection code
DISCONNECT_DESCRIPTION String  
CLIENT_PACKAGE String Registered application package which has been disconnected.
com.n7mobile.upnpplayer.RECEIVE_VOLUME_CHANGED Informs about volume change. REQ_CODE long Request identificator
VOLUME int Volume value from 0 to 100

Code table

STATE_CODEERROR_CODEREQ_STATUS_CODEDISCONNECT_CODE
NameValue(int)NameValue(int)NameValue(int)NameDescriptionValue(int)
PLAYING 1 DEVICE_DISCONNECT 101 OK 200 DIS_API_CONNECT Other application has connected to API what has disconnected current. 400
PAUSED 4 WIFI_DISCONNECT 102 ERROR ERROR_CODE DIS_PLAYER_CONNECT Upnp application has disconnected currently playing application. 401