Added in API level 1

Summary: Constants | Ctors | Methods | Inherited Methods

RingtoneManager

Kotlin |Java

public class RingtoneManager
extends Object

java.lang.Object
↳	android.media.RingtoneManager

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:

Ringtone

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` This constant was deprecated in API level 19. DRM ringtones are no longer supported
`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()` This method was deprecated in API level 19. DRM ringtones are no longer supported
`static Ringtone`	`getRingtone(Context context, Uri ringtoneUri)` Returns a `Ringtone` for a given sound URI.
`Ringtone`	`getRingtone(int position)` Gets a `Ringtone` for the ringtone at the given position in the `Cursor`.
`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.
`boolean`	`hasHapticChannels(int position)` Returns if the `Ringtone` at the given position in the `Cursor` contains haptic channels.
`static boolean`	`hasHapticChannels(Uri ringtoneUri)` Returns if the `Ringtone` from a given sound URI contains haptic channels or not.
`static boolean`	`hasHapticChannels(Context context, Uri ringtoneUri)` Returns if the `Ringtone` from a given sound URI contains haptics channels or not.
`int`	`inferStreamType()` Infers the volume 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 AssetFileDescriptor`	`openDefaultRingtoneUri(Context context, Uri uri)` Opens a raw file descriptor to read the data under the given default URI.
`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)` This method was deprecated in API level 19. DRM ringtones are no longer supported
`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.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

ACTION_RINGTONE_PICKER

Added in API level 1

public static final String ACTION_RINGTONE_PICKER

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,

Output: EXTRA_RINGTONE_PICKED_URI.

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

EXTRA_RINGTONE_DEFAULT_URI

Added in API level 1

public static final String EXTRA_RINGTONE_DEFAULT_URI

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 System#DEFAULT_RINGTONE_URI, System#DEFAULT_NOTIFICATION_URI, or System#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"

EXTRA_RINGTONE_EXISTING_URI

Added in API level 1

public static final String EXTRA_RINGTONE_EXISTING_URI

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 System#DEFAULT_RINGTONE_URI, System#DEFAULT_NOTIFICATION_URI, or System#DEFAULT_ALARM_ALERT_URI to have the "Default" item checked.

See also:

ACTION_RINGTONE_PICKER

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

EXTRA_RINGTONE_INCLUDE_DRM

Added in API level 1
Deprecated in API level 19

public static final String EXTRA_RINGTONE_INCLUDE_DRM

This constant was deprecated in API level 19.
DRM ringtones are no longer supported

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

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

EXTRA_RINGTONE_PICKED_URI

Added in API level 1

public static final String EXTRA_RINGTONE_PICKED_URI

Returned from the ringtone picker as a Uri.

It will be one of:

the picked ringtone,

a Uri that equals System#DEFAULT_RINGTONE_URI, System#DEFAULT_NOTIFICATION_URI, or System#DEFAULT_ALARM_ALERT_URI if the default was chosen,

null if the "Silent" item was picked.

See also:

ACTION_RINGTONE_PICKER

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

EXTRA_RINGTONE_SHOW_DEFAULT

Added in API level 1

public static final String EXTRA_RINGTONE_SHOW_DEFAULT

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

See also:

ACTION_RINGTONE_PICKER

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

EXTRA_RINGTONE_SHOW_SILENT

Added in API level 1

public static final String EXTRA_RINGTONE_SHOW_SILENT

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:

ACTION_RINGTONE_PICKER

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

EXTRA_RINGTONE_TITLE

Added in API level 1

public static final String EXTRA_RINGTONE_TITLE

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"

EXTRA_RINGTONE_TYPE

Added in API level 1

public static final String EXTRA_RINGTONE_TYPE

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"

ID_COLUMN_INDEX

Added in API level 1

public static final int ID_COLUMN_INDEX

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

Constant Value: 0 (0x00000000)

TITLE_COLUMN_INDEX

Added in API level 1

public static final int TITLE_COLUMN_INDEX

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

Constant Value: 1 (0x00000001)

TYPE_ALARM

Added in API level 1

public static final int TYPE_ALARM

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

Constant Value: 4 (0x00000004)

TYPE_ALL

Added in API level 1

public static final int TYPE_ALL

All types of sounds.

Constant Value: 7 (0x00000007)

TYPE_NOTIFICATION

Added in API level 1

public static final int TYPE_NOTIFICATION

Type that refers to sounds that are used for notifications.

Constant Value: 2 (0x00000002)

TYPE_RINGTONE

Added in API level 1

public static final int TYPE_RINGTONE

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

Constant Value: 1 (0x00000001)

URI_COLUMN_INDEX

Added in API level 1

public static final int URI_COLUMN_INDEX

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

Constant Value: 2 (0x00000002)

Public constructors

RingtoneManager

Added in API level 1

public RingtoneManager (Activity activity)

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

Parameters
`activity`	`Activity`: The activity used to get a managed cursor.

RingtoneManager

Added in API level 1

public RingtoneManager (Context context)

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

Parameters
`context`	`Context`: The context to used to get a cursor.

Public methods

getActualDefaultRingtoneUri

Added in API level 1

public static Uri getActualDefaultRingtoneUri (Context context, 
                int type)

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

Parameters
`context`	`Context`: A context used for querying.
`type`	`int`: The type whose default sound should be returned. One of `TYPE_RINGTONE`, `TYPE_NOTIFICATION`, or `TYPE_ALARM`.

Returns
`Uri`	A `Uri` pointing to the default sound for the sound type.

See also:

setActualDefaultRingtoneUri(Context, int, Uri)

getCursor

Added in API level 1

public Cursor getCursor ()

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 Cursor#close() the cursor. The cursor can be Cursor#deactivate() safely.

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

Note that the list of ringtones available will differ depending on whether the caller has the Manifest.permission.READ_EXTERNAL_STORAGE permission.

Returns
`Cursor`	A `Cursor` of all the ringtones available.

See also:

getDefaultType

Added in API level 1

public static int getDefaultType (Uri defaultRingtoneUri)

Returns the type of a default Uri.

Parameters
`defaultRingtoneUri`	`Uri`: The default `Uri`. For example, `System#DEFAULT_RINGTONE_URI`, `System#DEFAULT_NOTIFICATION_URI`, or `System#DEFAULT_ALARM_ALERT_URI`.

Returns
`int`	The type of the defaultRingtoneUri, or -1.

getDefaultUri

Added in API level 1

public static Uri getDefaultUri (int type)

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`	`int`: The ringtone type whose default should be returned.

Returns
`Uri`	The `Uri` of the default ringtone for the given type.

getIncludeDrm

Added in API level 1
Deprecated in API level 19

public boolean getIncludeDrm ()

This method was deprecated in API level 19.
DRM ringtones are no longer supported

Returns whether DRM ringtones will be included.

Returns
`boolean`	Whether DRM ringtones will be included.

See also:

Obsolete - always returns false

getRingtone

Added in API level 1

public static Ringtone getRingtone (Context context, 
                Uri ringtoneUri)

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`	`Context`: A context used to query.
`ringtoneUri`	`Uri`: The `Uri` of a sound or ringtone.

Returns
`Ringtone`	A `Ringtone` for the given URI, or null.

getRingtone

Added in API level 1

public Ringtone getRingtone (int position)

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

Parameters
`position`	`int`: The position (in the `Cursor`) of the ringtone.

Returns
`Ringtone`	A `Ringtone` pointing to the ringtone.

getRingtonePosition

Added in API level 1

public int getRingtonePosition (Uri ringtoneUri)

Gets the position of a Uri within this RingtoneManager.

Parameters
`ringtoneUri`	`Uri`: The `Uri` to retreive the position of.

Returns
`int`	The position of the `Uri`, or -1 if it cannot be found.

getRingtoneUri

Added in API level 1

public Uri getRingtoneUri (int position)

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

Parameters
`position`	`int`: The position (in the `Cursor`) of the ringtone.

Returns
`Uri`	A `Uri` pointing to the ringtone.

getStopPreviousRingtone

Added in API level 1

public boolean getStopPreviousRingtone ()

Returns
`boolean`

See also:

setStopPreviousRingtone(boolean)

getValidRingtoneUri

Added in API level 1

public static Uri getValidRingtoneUri (Context context)

Returns a valid ringtone URI. No guarantees on which it returns. If it cannot find one, returns null. If it can only find one on external storage and the caller doesn't have the Manifest.permission.READ_EXTERNAL_STORAGE permission, returns null.

Parameters
`context`	`Context`: The context to use for querying.

Returns
`Uri`	A ringtone URI, or null if one cannot be found.

hasHapticChannels

Added in API level 29

public boolean hasHapticChannels (int position)

Returns if the Ringtone at the given position in the Cursor contains haptic channels.

Parameters
`position`	`int`: The position (in the `Cursor`) of the ringtone.

Returns
`boolean`	true if the ringtone contains haptic channels.

hasHapticChannels

Added in API level 29

public static boolean hasHapticChannels (Uri ringtoneUri)

Returns if the Ringtone from a given sound URI contains haptic channels or not. As this function doesn't has a context to resolve the uri, the result may be wrong if the uri cannot be resolved correctly. Use hasHapticChannels(int) or hasHapticChannels(android.content.Context, android.net.Uri) instead when possible.

Parameters
`ringtoneUri`	`Uri`: The `Uri` of a sound or ringtone. This value cannot be `null`.

Returns
`boolean`	true if the ringtone contains haptic channels.

hasHapticChannels

Added in API level 33

public static boolean hasHapticChannels (Context context, 
                Uri ringtoneUri)

Returns if the Ringtone from a given sound URI contains haptics channels or not.

Parameters
`context`	`Context`: the `Context` to use when resolving the Uri. This value cannot be `null`.
`ringtoneUri`	`Uri`: the `Uri` of a sound or ringtone. This value cannot be `null`.

Returns
`boolean`	true if the ringtone contains haptic channels.

inferStreamType

Added in API level 3

public int inferStreamType ()

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

Returns
`int`	The stream type.

isDefault

Added in API level 1

public static boolean isDefault (Uri ringtoneUri)

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

Parameters
`ringtoneUri`	`Uri`: The ringtone `Uri` to be checked.

Returns
`boolean`	Whether the `Uri` is a default.

openDefaultRingtoneUri

Added in API level 29

public static AssetFileDescriptor openDefaultRingtoneUri (Context context, 
                Uri uri)

Opens a raw file descriptor to read the data under the given default URI.

Parameters
`context`	`Context`: the Context to use when resolving the Uri. This value cannot be `null`.
`uri`	`Uri`: The desired default URI to open. This value cannot be `null`.

Returns
`AssetFileDescriptor`	a new AssetFileDescriptor pointing to the file. You own this descriptor and are responsible for closing it when done. This value may be `null`.

Throws
`FileNotFoundException`	if the provided URI could not be opened.

See also:

getDefaultUri(int)

setActualDefaultRingtoneUri

Added in API level 1

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

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

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

See also:

getActualDefaultRingtoneUri(Context, int)

setIncludeDrm

Added in API level 1
Deprecated in API level 19

public void setIncludeDrm (boolean includeDrm)

This method was deprecated in API level 19.
DRM ringtones are no longer supported

Sets whether to include DRM ringtones.

Parameters
`includeDrm`	`boolean`: Whether to include DRM ringtones. Obsolete - no longer has any effect

setStopPreviousRingtone

Added in API level 1

public void setStopPreviousRingtone (boolean stopPreviousRingtone)

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

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

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

setType

Added in API level 1

public void setType (int type)

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

Parameters
`type`	`int`: The type(s), one or more of `TYPE_RINGTONE`, `TYPE_NOTIFICATION`, `TYPE_ALARM`, `TYPE_ALL`.

See also:

EXTRA_RINGTONE_TYPE

stopPreviousRingtone

Added in API level 1

public void stopPreviousRingtone ()

Stops playing the last Ringtone retrieved from this.