public class

RingtoneManager

extends Object
java.lang.Object
   ↳ android.media.RingtoneManager

Class Overview

RingtoneManager provides access to ringtones, notification, and other types of sounds. It manages querying the different media providers and combines the results into a single cursor. It also provides a Ringtone for each ringtone. We generically call these sounds ringtones, however the TYPE_RINGTONE refers to the type of sounds that are suitable for the phone ringer.

To show a ringtone picker to the user, use the ACTION_RINGTONE_PICKER intent to launch the picker as a subactivity.

See Also

Summary

Constants
String ACTION_RINGTONE_PICKER Activity Action: Shows a ringtone picker.
String EXTRA_RINGTONE_DEFAULT_URI Given to the ringtone picker as a Uri.
String EXTRA_RINGTONE_EXISTING_URI Given to the ringtone picker as a Uri.
String EXTRA_RINGTONE_INCLUDE_DRM Given to the ringtone picker as a boolean.
String EXTRA_RINGTONE_PICKED_URI Returned from the ringtone picker as a Uri.
String EXTRA_RINGTONE_SHOW_DEFAULT Given to the ringtone picker as a boolean.
String EXTRA_RINGTONE_SHOW_SILENT Given to the ringtone picker as a boolean.
String EXTRA_RINGTONE_TITLE Given to the ringtone picker as a CharSequence.
String EXTRA_RINGTONE_TYPE Given to the ringtone picker as an int.
int ID_COLUMN_INDEX The column index (in the cursor returned by getCursor() for the row ID.
int TITLE_COLUMN_INDEX The column index (in the cursor returned by getCursor() for the title.
int TYPE_ALARM Type that refers to sounds that are used for the alarm.
int TYPE_ALL All types of sounds.
int TYPE_NOTIFICATION Type that refers to sounds that are used for notifications.
int TYPE_RINGTONE Type that refers to sounds that are used for the phone ringer.
int URI_COLUMN_INDEX The column index (in the cursor returned by getCursor() for the media provider's URI.
Public Constructors
RingtoneManager(Activity activity)
Constructs a RingtoneManager.
RingtoneManager(Context context)
Constructs a RingtoneManager.
Public Methods
static Uri getActualDefaultRingtoneUri(Context context, int type)
Gets the current default sound's Uri.
Cursor getCursor()
Returns a Cursor of all the ringtones available.
static int getDefaultType(Uri defaultRingtoneUri)
Returns the type of a default Uri.
static Uri getDefaultUri(int type)
Returns the Uri for the default ringtone of a particular type.
boolean getIncludeDrm()
Returns whether DRM ringtones will be included.
Ringtone getRingtone(int position)
Gets a Ringtone for the ringtone at the given position in the Cursor.
static Ringtone getRingtone(Context context, Uri ringtoneUri)
Returns a Ringtone for a given sound URI.
int getRingtonePosition(Uri ringtoneUri)
Gets the position of a Uri within this RingtoneManager.
Uri getRingtoneUri(int position)
Gets a Uri for the ringtone at the given position in the Cursor.
boolean getStopPreviousRingtone()
static Uri getValidRingtoneUri(Context context)
Returns a valid ringtone URI.
int inferStreamType()
Infers the playback stream type based on what type of ringtones this manager is returning.
static boolean isDefault(Uri ringtoneUri)
Returns whether the given Uri is one of the default ringtones.
static void setActualDefaultRingtoneUri(Context context, int type, Uri ringtoneUri)
Sets the Uri of the default sound for a given sound type.
void setIncludeDrm(boolean includeDrm)
Sets whether to include DRM ringtones.
void setStopPreviousRingtone(boolean stopPreviousRingtone)
Whether retrieving another Ringtone will stop playing the previously retrieved Ringtone.
void setType(int type)
Sets which type(s) of ringtones will be listed by this.
void stopPreviousRingtone()
Stops playing the last Ringtone retrieved from this.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_RINGTONE_PICKER

Since: API Level 1

Activity Action: Shows a ringtone picker.

Input: EXTRA_RINGTONE_EXISTING_URI, EXTRA_RINGTONE_SHOW_DEFAULT, EXTRA_RINGTONE_SHOW_SILENT, EXTRA_RINGTONE_TYPE, EXTRA_RINGTONE_DEFAULT_URI, EXTRA_RINGTONE_TITLE, EXTRA_RINGTONE_INCLUDE_DRM.

Output: EXTRA_RINGTONE_PICKED_URI.

Constant Value: "android.intent.action.RINGTONE_PICKER"

public static final String EXTRA_RINGTONE_DEFAULT_URI

Since: API Level 1

Given to the ringtone picker as a Uri. The Uri of the ringtone to play when the user attempts to preview the "Default" ringtone. This can be one of DEFAULT_RINGTONE_URI, DEFAULT_NOTIFICATION_URI, or DEFAULT_ALARM_ALERT_URI to have the "Default" point to the current sound for the given default sound type. If you are showing a ringtone picker for some other type of sound, you are free to provide any Uri here.

Constant Value: "android.intent.extra.ringtone.DEFAULT_URI"

public static final String EXTRA_RINGTONE_EXISTING_URI

Since: API Level 1

Given to the ringtone picker as a Uri. The Uri of the current ringtone, which will be used to show a checkmark next to the item for this Uri. If showing an item for "Default" (@see EXTRA_RINGTONE_SHOW_DEFAULT), this can also be one of DEFAULT_RINGTONE_URI, DEFAULT_NOTIFICATION_URI, or DEFAULT_ALARM_ALERT_URI to have the "Default" item checked.

See Also
Constant Value: "android.intent.extra.ringtone.EXISTING_URI"

public static final String EXTRA_RINGTONE_INCLUDE_DRM

Since: API Level 1

Given to the ringtone picker as a boolean. Whether to include DRM ringtones.

Constant Value: "android.intent.extra.ringtone.INCLUDE_DRM"

public static final String EXTRA_RINGTONE_PICKED_URI

Since: API Level 1

Returned from the ringtone picker as a Uri.

It will be one of:

  • the picked ringtone,
  • a Uri that equals DEFAULT_RINGTONE_URI, DEFAULT_NOTIFICATION_URI, or DEFAULT_ALARM_ALERT_URI if the default was chosen,
  • null if the "Silent" item was picked.

    • See Also
    Constant Value: "android.intent.extra.ringtone.PICKED_URI"

    public static final String EXTRA_RINGTONE_SHOW_DEFAULT

    Since: API Level 1

    Given to the ringtone picker as a boolean. Whether to show an item for "Default".

    See Also
    Constant Value: "android.intent.extra.ringtone.SHOW_DEFAULT"

    public static final String EXTRA_RINGTONE_SHOW_SILENT

    Since: API Level 1

    Given to the ringtone picker as a boolean. Whether to show an item for "Silent". If the "Silent" item is picked, EXTRA_RINGTONE_PICKED_URI will be null.

    See Also
    Constant Value: "android.intent.extra.ringtone.SHOW_SILENT"

    public static final String EXTRA_RINGTONE_TITLE

    Since: API Level 1

    Given to the ringtone picker as a CharSequence. The title to show for the ringtone picker. This has a default value that is suitable in most cases.

    Constant Value: "android.intent.extra.ringtone.TITLE"

    public static final String EXTRA_RINGTONE_TYPE

    Since: API Level 1

    Given to the ringtone picker as an int. Specifies which ringtone type(s) should be shown in the picker. One or more of TYPE_RINGTONE, TYPE_NOTIFICATION, TYPE_ALARM, or TYPE_ALL (bitwise-ored together).

    Constant Value: "android.intent.extra.ringtone.TYPE"

    public static final int ID_COLUMN_INDEX

    Since: API Level 1

    The column index (in the cursor returned by getCursor() for the row ID.

    Constant Value: 0 (0x00000000)

    public static final int TITLE_COLUMN_INDEX

    Since: API Level 1

    The column index (in the cursor returned by getCursor() for the title.

    Constant Value: 1 (0x00000001)

    public static final int TYPE_ALARM

    Since: API Level 1

    Type that refers to sounds that are used for the alarm.

    Constant Value: 4 (0x00000004)

    public static final int TYPE_ALL

    Since: API Level 1

    All types of sounds.

    Constant Value: 7 (0x00000007)

    public static final int TYPE_NOTIFICATION

    Since: API Level 1

    Type that refers to sounds that are used for notifications.

    Constant Value: 2 (0x00000002)

    public static final int TYPE_RINGTONE

    Since: API Level 1

    Type that refers to sounds that are used for the phone ringer.

    Constant Value: 1 (0x00000001)

    public static final int URI_COLUMN_INDEX

    Since: API Level 1

    The column index (in the cursor returned by getCursor() for the media provider's URI.

    Constant Value: 2 (0x00000002)

    Public Constructors

    public RingtoneManager (Activity activity)

    Since: API Level 1

    Constructs a RingtoneManager. This constructor is recommended as its constructed instance manages cursor(s).

    Parameters
    activity The activity used to get a managed cursor.

    public RingtoneManager (Context context)

    Since: API Level 1

    Constructs a RingtoneManager. The instance constructed by this constructor will not manage the cursor(s), so the client should handle this itself.

    Parameters
    context The context to used to get a cursor.

    Public Methods

    public static Uri getActualDefaultRingtoneUri (Context context, int type)

    Since: API Level 1

    Gets the current default sound's Uri. This will give the actual sound Uri, instead of using this, most clients can use DEFAULT_RINGTONE_URI.

    Parameters
    context A context used for querying.
    type The type whose default sound should be returned. One of TYPE_RINGTONE, TYPE_NOTIFICATION, or TYPE_ALARM.
    Returns
    • A Uri pointing to the default sound for the sound type.
    See Also

    public Cursor getCursor ()

    Since: API Level 1

    Returns a Cursor of all the ringtones available. The returned cursor will be the same cursor returned each time this method is called, so do not close() the cursor. The cursor can be deactivate() safely.

    If RingtoneManager(Activity) was not used, the caller should manage the returned cursor through its activity's life cycle to prevent leaking the cursor.

    Returns
    • A Cursor of all the ringtones available.
    See Also

    public static int getDefaultType (Uri defaultRingtoneUri)

    Since: API Level 1

    Returns the type of a default Uri.

    Parameters
    defaultRingtoneUri The default Uri. For example, DEFAULT_RINGTONE_URI, DEFAULT_NOTIFICATION_URI, or DEFAULT_ALARM_ALERT_URI.
    Returns
    • The type of the defaultRingtoneUri, or -1.

    public static Uri getDefaultUri (int type)

    Since: API Level 1

    Returns the Uri for the default ringtone of a particular type. Rather than returning the actual ringtone's sound Uri, this will return the symbolic Uri which will resolved to the actual sound when played.

    Parameters
    type The ringtone type whose default should be returned.
    Returns
    • The Uri of the default ringtone for the given type.

    public boolean getIncludeDrm ()

    Since: API Level 1

    Returns whether DRM ringtones will be included.

    Returns
    • Whether DRM ringtones will be included.
    See Also

    public Ringtone getRingtone (int position)

    Since: API Level 1

    Gets a Ringtone for the ringtone at the given position in the Cursor.

    Parameters
    position The position (in the Cursor) of the ringtone.
    Returns

    public static Ringtone getRingtone (Context context, Uri ringtoneUri)

    Since: API Level 1

    Returns a Ringtone for a given sound URI.

    If the given URI cannot be opened for any reason, this method will attempt to fallback on another sound. If it cannot find any, it will return null.

    Parameters
    context A context used to query.
    ringtoneUri The Uri of a sound or ringtone.
    Returns

    public int getRingtonePosition (Uri ringtoneUri)

    Since: API Level 1

    Gets the position of a Uri within this RingtoneManager.

    Parameters
    ringtoneUri The Uri to retreive the position of.
    Returns
    • The position of the Uri, or -1 if it cannot be found.

    public Uri getRingtoneUri (int position)

    Since: API Level 1

    Gets a Uri for the ringtone at the given position in the Cursor.

    Parameters
    position The position (in the Cursor) of the ringtone.
    Returns
    • A Uri pointing to the ringtone.

    public boolean getStopPreviousRingtone ()

    Since: API Level 1

    See Also

    public static Uri getValidRingtoneUri (Context context)

    Since: API Level 1

    Returns a valid ringtone URI. No guarantees on which it returns. If it cannot find one, returns null.

    Parameters
    context The context to use for querying.
    Returns
    • A ringtone URI, or null if one cannot be found.

    public int inferStreamType ()

    Since: API Level 3

    Infers the playback stream type based on what type of ringtones this manager is returning.

    Returns
    • The stream type.

    public static boolean isDefault (Uri ringtoneUri)

    Since: API Level 1

    Returns whether the given Uri is one of the default ringtones.

    Parameters
    ringtoneUri The ringtone Uri to be checked.
    Returns
    • Whether the Uri is a default.

    public static void setActualDefaultRingtoneUri (Context context, int type, Uri ringtoneUri)

    Since: API Level 1

    Sets the Uri of the default sound for a given sound type.

    Parameters
    context A context used for querying.
    type The type whose default sound should be set. One of TYPE_RINGTONE, TYPE_NOTIFICATION, or TYPE_ALARM.
    ringtoneUri A Uri pointing to the default sound to set.
    See Also

    public void setIncludeDrm (boolean includeDrm)

    Since: API Level 1

    Sets whether to include DRM ringtones.

    Parameters
    includeDrm Whether to include DRM ringtones.

    public void setStopPreviousRingtone (boolean stopPreviousRingtone)

    Since: API Level 1

    Whether retrieving another Ringtone will stop playing the previously retrieved Ringtone.

    If this is false, make sure to stop() any previous ringtones to free resources.

    Parameters
    stopPreviousRingtone If true, the previously retrieved Ringtone will be stopped.

    public void setType (int type)

    Since: API Level 1

    Sets which type(s) of ringtones will be listed by this.

    Parameters
    type The type(s), one or more of TYPE_RINGTONE, TYPE_NOTIFICATION, TYPE_ALARM, TYPE_ALL.
    See Also

    public void stopPreviousRingtone ()

    Since: API Level 1

    Stops playing the last Ringtone retrieved from this.