We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K

ringtone (Ringtone Service)

Phone5.0.0(12)+Tablet5.0.0(12)+
Last updated: 2026-09-04 06:52
Content overview
Expand

The ringtone module provides the function of setting ringtones.

Since: 5.0.0(12)

Modules to Import

Collapse
Word wrap
Dark theme
Copy code
  1. import { ringtone } from '@kit.RingtoneKit';

RingtoneType

Phone5.0.0(12)+Tablet5.0.0(12)+

Enumeration of ringtone types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Expand
Name Value Description
CALL 0 Ringtone for incoming calls.
MESSAGE 1 Ringtone for SMS messages.
NOTIFICATION 2 Ringtone for notifications.
ALARM 3 Ringtone for alarms.

RingtoneErrors

Phone5.0.0(12)+Tablet5.0.0(12)+

Enumeration of error codes of the APIs for setting ringtones and obtaining supported ringtone types and ringtone file types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Expand
Name Value Description
ERROR_INVALID_PARAM 401 Invalid parameter.
ERROR_USER_CANCELED 1011600001 The operation is canceled by the user.
ERROR_FILE_NOT_FOUND 1011600002 The file does not exist.
ERROR_SHOW_FAILED 1011600003 The ringtone dialog box fails to be displayed.
ERROR_CALL_SYSTEM_API_FAILED 1011600004 Failed to call the system API.
ERROR_DATA_TYPE_NOT_MATCHED 1011600005 Unmatched file type. Since: 26.0.0
ERROR_SYSTEM 1011699999 Internal system error.

ringtone.getSupportedRingtoneTypes

Phone5.0.0(12)+Tablet5.0.0(12)+

getSupportedRingtoneTypes(): Array<RingtoneType>

Queries custom ringtone types supported by the system.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Returns:

Expand
Type Description
Array<RingtoneType> Custom ringtone types supported by the system.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. import { ringtone } from '@kit.RingtoneKit';
  2. import { JSON } from '@kit.ArkTS';
  3. import { hilog } from '@kit.PerformanceAnalysisKit';
  4. 

  5. const APP_TAG = 'Msc_Demo'
  6. const DOMAIN = 0x0001
  7. 

  8. @Entry
  9. @Component
  10. struct Index {
  11.   build() {
  12.     Stack() {
  13.       Column() {
  14.         Button('Query Supported Custom Ringtone Types')
  15.           .width(200)
  16.           .height(50)
  17.           .onClick(() => {
  18.             let typeList: ringtone.RingtoneType[] = ringtone.getSupportedRingtoneTypes()
  19.             hilog.info(DOMAIN, APP_TAG, `getSupportedRingtoneTypes: ${JSON.stringify(typeList)}`);
  20.           })
  21.       }
  22.       .width('100%')
  23.       .height('100%')
  24.       .backgroundColor(Color.Pink)
  25.     }
  26.     .height('100%')
  27.     .width('100%')
  28.   }
  29. }

ringtone.getSupportedRingtoneTypes

Phone26.0.0+Tablet26.0.0+

getSupportedRingtoneTypes(mediaType: uniformTypeDescriptor.UniformDataType): Array<RingtoneType>

Queries custom ringtone types supported by the system.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 26.0.0

Parameters:

Expand
Parameter Type Mandatory Description
mediaType uniformTypeDescriptor.UniformDataType Yes File type to be queried.

Returns:

Expand
Type Description
Array<RingtoneType> Custom ringtone types supported by the system.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. import { ringtone } from '@kit.RingtoneKit';
  2. import { JSON } from '@kit.ArkTS';
  3. import { uniformTypeDescriptor } from '@kit.ArkData';
  4. import { hilog } from '@kit.PerformanceAnalysisKit';
  5. 

  6. const APP_TAG = 'Msc_Demo'
  7. const DOMAIN = 0x0001
  8. 

  9. @Entry
  10. @Component
  11. struct Index {
  12.   build() {
  13.     Stack() {
  14.       Column() {
  15.         Button('Query Supported Custom Ringtone Types')
  16.           .width(200)
  17.           .height(50)
  18.           .onClick(() => {
  19.             let typeList: ringtone.RingtoneType[] = ringtone.getSupportedRingtoneTypes(uniformTypeDescriptor.UniformDataType.AUDIO)
  20.             hilog.info(DOMAIN, APP_TAG, `getSupportedRingtoneTypes: ${JSON.stringify(typeList)}`);
  21.           })
  22.       }
  23.       .width('100%')
  24.       .height('100%')
  25.       .backgroundColor(Color.Pink)
  26.     }
  27.     .height('100%')
  28.     .width('100%')
  29.   }
  30. }

ringtone.getSupportedDataTypes

Phone5.0.0(12)+Tablet5.0.0(12)+

getSupportedDataTypes(ringtoneType: RingtoneType): Array<uniformTypeDescriptor.UniformDataType>

Queries the file types supported by a ringtone type.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Parameters:

Expand
Parameter Type Mandatory Description
ringtoneType RingtoneType Yes Ringtone type to be queried.

Returns:

Expand
Type Description
Array<uniformTypeDescriptor.UniformDataType> File types supported by a ringtone type.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Expand
ID Error Message
401 Parameter error. Possible causes:ringtoneType is invalid.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. import { ringtone } from '@kit.RingtoneKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { uniformTypeDescriptor } from '@kit.ArkData';
  4. import { JSON } from '@kit.ArkTS';
  5. import { hilog } from '@kit.PerformanceAnalysisKit';
  6. 

  7. const APP_TAG = 'Msc_Demo'
  8. const DOMAIN = 0x0001
  9. 

  10. @Entry
  11. @Component
  12. struct Index {
  13.   build() {
  14.     Stack() {
  15.       Column() {
  16.         Button('Query Supported File Types')
  17.           .width(200)
  18.           .height(50)
  19.           .onClick(() => {
  20.             try {
  21.               let typeList: uniformTypeDescriptor.UniformDataType[] =
  22.                 ringtone.getSupportedDataTypes(ringtone.RingtoneType.NOTIFICATION)
  23.               hilog.info(DOMAIN, APP_TAG, `getSupportedDataType: ${JSON.stringify(typeList)}`);
  24.             } catch (error) {
  25.               let err: BusinessError = error as BusinessError;
  26.               hilog.error(DOMAIN, APP_TAG,
  27.                 `getSupportedDataType error message: ${err.message}, error code: ${err.code}`);
  28.             }
  29.           })
  30.       }
  31.       .width('100%')
  32.       .height('100%')
  33.       .backgroundColor(Color.Pink)
  34.     }
  35.     .height('100%')
  36.     .width('100%')
  37.   }
  38. }

ringtone.getSupportedMaxDuration

Phone5.0.0(12)+Tablet5.0.0(12)+

getSupportedMaxDuration(ringtoneType: RingtoneType, dataType: uniformTypeDescriptor.UniformDataType): number

Queries the maximum file duration supported by different ringtone types and file types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Parameters:

Expand
Parameter Type Mandatory Description
ringtoneType RingtoneType Yes Ringtone type to be queried.
dataType uniformTypeDescriptor.UniformDataType Yes File type to be queried.

Returns:

Expand
Type Description
number Maximum duration (unit: second) supported by the ringtone and file types. The maximum duration for an alarm ringtone is 300s, for an SMS message ringtone and notification ringtone is 7s, and for an incoming call ringtone is 60s.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Expand
ID Error Message
401 Parameter error. Possible causes:data type does not match the ringtone type.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. import { ringtone } from '@kit.RingtoneKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { uniformTypeDescriptor } from '@kit.ArkData';
  4. import { hilog } from '@kit.PerformanceAnalysisKit';
  5. 

  6. const APP_TAG = 'Msc_Demo'
  7. const DOMAIN = 0x0001
  8. 

  9. @Entry
  10. @Component
  11. struct Index {
  12.   build() {
  13.     Stack() {
  14.       Column() {
  15.         Button('Query Maximum Duration')
  16.           .width(200)
  17.           .height(50)
  18.           .onClick(() => {
  19.             try {
  20.               let maxDuration: number =
  21.                 ringtone.getSupportedMaxDuration(ringtone.RingtoneType.MESSAGE,
  22.                   uniformTypeDescriptor.UniformDataType.MP3)
  23.               hilog.info(DOMAIN, APP_TAG, `getSupportedMaxDuration: ${maxDuration}`);
  24.             } catch (error) {
  25.               let err: BusinessError = error as BusinessError;
  26.               hilog.error(DOMAIN, APP_TAG,
  27.                 `getSupportedMaxDuration error message: ${err.message}, error code: ${err.code}`);
  28.             }
  29.           })
  30.       }
  31.       .width('100%')
  32.       .height('100%')
  33.       .backgroundColor(Color.Pink)
  34.     }
  35.     .height('100%')
  36.     .width('100%')
  37.   }
  38. }

ringtone.getSupportedMaxSize

Phone26.0.0+Tablet26.0.0+

getSupportedMaxSize(ringtoneType: RingtoneType, dataType: uniformTypeDescriptor.UniformDataType): number

Queries the maximum file size supported by different ringtone types and file types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 26.0.0

Parameters:

Expand
Parameter Type Mandatory Description
ringtoneType RingtoneType Yes Ringtone type to be queried.
dataType uniformTypeDescriptor.UniformDataType Yes File type to be queried.

Returns:

Expand
Type Description
number Maximum file size (unit: KB) supported by the ringtone and file types. The maximum size of a video file is 200 MB. If the size of an audio file is not limited, -1 is returned.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Expand
ID Error Message
1011600005 The data type does not match the ringtone type.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. import { ringtone } from '@kit.RingtoneKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { uniformTypeDescriptor } from '@kit.ArkData';
  4. import { hilog } from '@kit.PerformanceAnalysisKit';
  5. 

  6. const APP_TAG = 'Msc_Demo'
  7. const DOMAIN = 0x0001
  8. 

  9. @Entry
  10. @Component
  11. struct Index {
  12.   build() {
  13.     Stack() {
  14.       Column() {
  15.         Button('Query File Size Limit')
  16.           .width(200)
  17.           .height(50)
  18.           .onClick(() => {
  19.             try {
  20.               let maxSize: number =
  21.                 ringtone.getSupportedMaxSize(ringtone.RingtoneType.CALL,
  22.                   uniformTypeDescriptor.UniformDataType.MP3)
  23.               hilog.info(DOMAIN, APP_TAG, `getSupportedMaxSize: ${maxSize}`);
  24.             } catch (error) {
  25.               let err: BusinessError = error as BusinessError;
  26.               hilog.error(DOMAIN, APP_TAG,
  27.                 `getSupportedMaxSize error message: ${err.message}, error code: ${err.code}`);
  28.             }
  29.           })
  30.       }
  31.       .width('100%')
  32.       .height('100%')
  33.       .backgroundColor(Color.Pink)
  34.     }
  35.     .height('100%')
  36.     .width('100%')
  37.   }
  38. }

ringtone.startRingtoneSetting

Phone5.0.0(12)+Tablet5.0.0(12)+

startRingtoneSetting(context: common.UIAbilityContext, path: string, name: string, callback: AsyncCallback<RingtoneType>): void

Opens the ringtone setting pop-up window and returns the type of the tapped ringtone. This API returns the result asynchronously through a callback.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Parameters:

Expand
Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
path string Yes Path of the file on which you have the access permission.
name string Yes File name. The value contains a maximum of 1,000 characters.
callback AsyncCallback<RingtoneType> Yes Callback used to return the ringtone type set by the user.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Expand
ID Error Message
401 Parameter error. Possible causes: context is invalid.
1011600001 User canceled.
1011600002 The media file is not found.
1011600003 Failed to show the dialog box.
1011600004 Failed to call the system API.
1011699999 System exception.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. import { common } from '@kit.AbilityKit';
  2. import { ringtone } from '@kit.RingtoneKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. import { JSON } from '@kit.ArkTS';
  5. import { hilog } from '@kit.PerformanceAnalysisKit';
  6. 

  7. const APP_TAG = 'Msc_Demo'
  8. const DOMAIN = 0x0001
  9. 

  10. @Entry
  11. @Component
  12. struct Index {
  13.   private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
  14. 

  15.   build() {
  16.     Stack() {
  17.       Column() {
  18.         Button('Set Ringtone OGG Format')
  19.           .width(200)
  20.           .height(50)
  21.           .onClick(() => {
  22.             let audioPath: string = this.context.filesDir + '/test.ogg'
  23.             let splitList = audioPath.split('/')
  24.             let fileName = splitList[splitList.length - 1]
  25.             hilog.info(DOMAIN, APP_TAG, `audioPath: ${audioPath}`)
  26.             hilog.info(DOMAIN, APP_TAG, `fileName: ${fileName}`)
  27. 

  28.             try {
  29.               ringtone.startRingtoneSetting(this.context, audioPath, fileName, (err, res) => {
  30.                 hilog.info(DOMAIN, APP_TAG, `Return value: ${JSON.stringify(res)}`)
  31.               })
  32.             } catch (error) {
  33.               let err: BusinessError = error as BusinessError;
  34.               hilog.error(DOMAIN, APP_TAG,
  35.                 `accessSync failed with error message: ${err.message}, error code: ${err.code}`);
  36.             }
  37.           })
  38.       }
  39.       .width('100%')
  40.       .height('100%')
  41.       .backgroundColor(Color.Pink)
  42.     }
  43.     .height('100%')
  44.     .width('100%')
  45.   }
  46. }

ringtone.startRingtoneSetting

Phone5.0.0(12)+Tablet5.0.0(12)+

startRingtoneSetting(context: common.UIAbilityContext, path: string, name: string): Promise<RingtoneType>

Opens the ringtone setting pop-up window and returns the type of the tapped ringtone. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Ringtone.Core

Since: 5.0.0(12)

Parameters:

Expand
Parameter Type Mandatory Description
context common.UIAbilityContext Yes UIAbility context.
path string Yes Path of the file on which you have the access permission.
name string Yes File name. The value contains a maximum of 1,000 characters.

Returns:

Expand
Type Description
Promise<RingtoneType> Promise used to return the ringtone type set by the user.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Expand
ID Error Message
401 Parameter error. Possible causes: context is invalid.
1011600001 User canceled.
1011600002 The media file is not found.
1011600003 Failed to show the dialog box.
1011600004 Failed to call the system API.
1011699999 System exception.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. import { common } from '@kit.AbilityKit';
  2. import { ringtone } from '@kit.RingtoneKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. import { JSON } from '@kit.ArkTS';
  5. import { hilog } from '@kit.PerformanceAnalysisKit';
  6. 

  7. const APP_TAG = 'Msc_Demo'
  8. const DOMAIN = 0x0001
  9. 

  10. @Entry
  11. @Component
  12. struct Index {
  13.   private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
  14. 

  15.   build() {
  16.     Stack() {
  17.       Column() {
  18.         Button('Set Ringtone OGG Format')
  19.           .width(200)
  20.           .height(50)
  21.           .onClick(() => {
  22.             let audioPath: string = this.context.filesDir + '/test.ogg'
  23.             let splitList = audioPath.split('/')
  24.             let fileName = splitList[splitList.length - 1]
  25.             hilog.info(DOMAIN, APP_TAG, `audioPath: ${audioPath}`)
  26.             hilog.info(DOMAIN, APP_TAG, `fileName: ${fileName}`)
  27. 

  28.             try {
  29.               ringtone.startRingtoneSetting(this.context, audioPath, fileName).then(res => {
  30.                 hilog.info(DOMAIN, APP_TAG, `Return value: ${JSON.stringify(res)}`)
  31.               })
  32.             } catch (error) {
  33.               let err: BusinessError = error as BusinessError;
  34.               hilog.error(DOMAIN, APP_TAG,
  35.                 `accessSync failed with error message: ${err.message}, error code: ${err.code}`);
  36.             }
  37.           })
  38.       }
  39.       .width('100%')
  40.       .height('100%')
  41.       .backgroundColor(Color.Pink)
  42.     }
  43.     .height('100%')
  44.     .width('100%')
  45.   }
  46. }
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in References
Enter a keyword.