目录

TextReader (Reading Control)

The TextReader uses AI capabilities to convert text into speech in real time and read it aloud. It supports multiple languages, timbres, and speech speeds, and can be integrated into apps used for browsing text content such as news, education, and reading. This helps users efficiently access information through text-to-speech in scenarios where direct reading is restricted, such as driving or exercising. Multiple playback modes are supported, such as Minibar and playback panel.

Since: 5.0.0(12)

Modules to Import

import { TextReader } from '@kit.SpeechKit';

Precautions

Before calling the TextReader APIs, you must call init to initialize the TextReader. Otherwise, an error will be reported.

init

init(context: common.BaseContext, readParams: ReaderParam): Promise<void>

Initializes the TextReader, that is, the TTS engine and underlying player. If the initialization fails, the corresponding error code is returned.

This API returns the result asynchronously through a promise. To configure long-duration permissions, please refer to step 9 in the development guide.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

Required permission: ohos.permission.KEEP_BACKGROUND_RUNNING

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
context common.BaseContext Yes App context.
readParams ReaderParam Yes Reading parameters.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

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

ID Error Message
201 Permission denied. Interface caller does not have permission ohos.permission.KEEP_BACKGROUND_RUNNING.
401 Parameter error.
1010600011 Initialize failed.

Example:

import { TextReader } from '@kit.SpeechKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  // Obtain the application context.

  async aboutToAppear(): Promise<void> {
    let context: Context | undefined = this.getUIContext().getHostContext();
    if (context) {
      // Set reading parameters.
      const readerParams: TextReader.ReaderParam = {
        isVoiceBrandVisible: true,
        businessBrandInfo: {
          panelName: 'AI Reader',
          panelIcon: $r('app.media.startIcon')
        }
      };
      // Initialize the TextReader.
      await TextReader.init(context, readerParams).then(() => {
        console.info(`TextReader succeeded in initializing.`);
      }).catch((e: BusinessError) => {
        console.error(`TextReader failed to initialize. Code: ${e.code}, message: ${e.message}`);
      });
    }
  }

  build() {
    // ...
  }
}

start

start(readInfoList: ReadInfo[], articleId?: string): Promise<void>

Start playback through the TextReader. If the playback fails, the corresponding error code is returned.

This API returns the result asynchronously through a promise.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
readInfoList ReadInfo[] Yes

List of articles to read.

- If the first article in the list has a category (i.e., the article has the category or categoryObject field specified) and the following articles do not, the following articles will be categorized under Others.

- If the first article in the list is not categorized, the following articles, even if categorized, will not have their categories applied.
articleId string No Article ID. If articleId is not passed, the first article in the reading list will be played by default, followed by the next. If articleId is passed, the specified article will be played, followed by the next. (The article ID must be unique. Otherwise, the first article with the same ID will be automatically read when you access the articles with the same ID from the list.)

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

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

ID Error Message
401 Parameter error.
1010600012 The TextReader is not initialized.
1010600013 Text-to-speech engine error.
1010600014 AudioRenderer play error.
1010600015 Audio decode error.
1010600016 AVSession error.
1010600017 Other error.

Example:

import { TextReader } from '@kit.SpeechKit';
import { BusinessError } from '@kit.BasicServicesKit';

const readInfoList: TextReader.ReadInfo[] = [{
  id: '001',
  title: {
    text:'*Title of the text to read*',
    isClickable:true
  },
  author:{
    text:'*Author of the text to read*',
    isClickable:true
  },
  date: {
    text:'2024/01/01',
    isClickable:false
  },
  bodyInfo: '*Text body to read*'
}];
// Start the TextReader.
TextReader.start(readInfoList).then(() => {
  console.info(`TextReader succeeded in starting`);
}).catch((e: BusinessError) => {
  console.error(`TextReader failed to start. Code: ${e.code}, message: ${e.message}`);
});

start

start(readInfoList: ReadInfo[], articleId: string | undefined, startParams: StartParams): Promise<void>

Start the TextReader. You can set the startParams parameter to hide the minibar. If the playback fails, the corresponding error code is returned.

This API returns the result asynchronously through a promise.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Parameter Type Mandatory Description
readInfoList ReadInfo[] Yes

List of articles to read.

- If the first article in the list has a category (i.e., the article has the category or categoryObject field specified) and the following articles do not, the following articles will be categorized under Others.

- If the first article in the list is not categorized, the following articles, even if categorized, will not have their categories applied.
articleId string | undefined Yes Article ID. (The article ID must be unique; otherwise, the first article with the same ID in the list will be automatically selected.) If articleId is not passed, the first article in the list will be played by default. If articleId is passed, articles will be played in sequence from the specified article onward.
startParams StartParams Yes Playback start parameters of the TextReader.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

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

ID Error Message
401 Parameter error.
1010600012 The TextReader is not initialized.
1010600013 Text-to-speech engine error.
1010600014 AudioRenderer play error.
1010600015 Audio decode error.
1010600016 AVSession error.
1010600017 Other error.

Example:

import { TextReader } from '@kit.SpeechKit';
import { BusinessError } from '@kit.BasicServicesKit';

const readInfoList: TextReader.ReadInfo[] = [{
  id: '001',
  title: {
    text:'*Title of the text to read*',
    isClickable:true
  },
  author:{
    text:'*Author of the text to read*',
    isClickable:true
  },
  date: {
    text:'2024/01/01',
    isClickable:false
  },
  bodyInfo: '*Text body to read*'
}];
const startParams: TextReader.StartParams = {
  isMinibarHidden: false,
  callbackParam: '0'
};
// Start the TextReader.
TextReader.start(readInfoList, undefined, startParams).then(() => {
  console.info(`TextReader succeeded in starting`);
}).catch((e: BusinessError) => {
  console.error(`TextReader failed to start. Code: ${e.code}, message: ${e.message}`);
});

stop

stop(): Promise<void>

Stops reading, closes the playback panel, unregisters the listeners, and resets parameters.

This API returns the result asynchronously through a promise.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.

Example:

import { TextReader } from '@kit.SpeechKit';
import { BusinessError } from '@kit.BasicServicesKit';

TextReader.stop().then(() => {
  console.info(`TextReader succeeded in stopping.`);
}).catch((e: BusinessError) => {
  console.error(`TextReader failed to stop. Code: ${e.code}, message: ${e.message}`);
});

resetParam

resetParam(paramName: ResetParamType) : void

Resets initialization parameters and clears the reading list.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Parameter Type Mandatory Description
paramName ResetParamType Yes Type of the parameter to be reset.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.resetParam(TextReader.ResetParamType.BAR_PARAM);
  console.info(`TextReader succeeded in resetParam.`);
} catch (e) {
  console.error(`TextReader failed to resetParam. Code: ${e.code}, message: ${e.message}`);
}

release

release(): Promise<void>

Releases all resources of the TextReader.

This API returns the result asynchronously through a promise.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.
1010600020 Release error.

Example:

import { TextReader } from '@kit.SpeechKit';
import { BusinessError } from '@kit.BasicServicesKit';

TextReader.release().then(() => {
  console.info(`TextReader succeeded in releasing.`);
}).catch((e: BusinessError) => {
  console.error(`TextReader failed to release. Code: ${e.code}, message: ${e.message}`);
});

pause

pause(): void

Pauses playback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.pause();
} catch (e) {
  console.error(`TextReader failed to pause. Code: ${e.code}, message: ${e.message}`);
}

resume

resume(): void

Resumes playback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.
1010600013 Text-to-speech engine error.
1010600014 AudioRenderer play error.
1010600015 Audio decode error.
1010600016 AVSession error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.resume();
} catch (e) {
  console.error(`TextReader failed to resume. Code: ${e.code}, message: ${e.message}`);
}

playPrev

playPrev(): void

Plays the previous article.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.
1010600018 playPrev failed.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.playPrev();
} catch (e) {
  console.error(`TextReader failed to play previous article. Code: ${e.code}, message: ${e.message}`);
}

playNext

playNext(): void

Plays the next article.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.
1010600019 playNext failed.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.playNext();
} catch (e) {
  console.error(`TextReader failed to play next article. Code: ${e.code}, message: ${e.message}`);
}

hidePanel

hidePanel(): void

Hides the playback panel.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.hidePanel();
} catch (e) {
  console.error(`TextReader failed to hide panel. Code: ${e.code}, message: ${e.message}`);
}

showPanel

showPanel(): void

Shows the playback panel.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.showPanel();
} catch (e) {
  console.error(`TextReader failed to show panel. Code: ${e.code}, message: ${e.message}`);
}

showMinibar

showMinibar(): void

Shows the minibar.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.showMinibar();
} catch (e) {
  console.error(`TextReader failed to show Minibar. Code: ${e.code}, message: ${e.message}`);
}

hideMinibar

hideMinibar(): void

Hides the minibar.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Error codes:

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

ID Error Message
1010600012 The TextReader is not initialized.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.hideMinibar();
} catch (e) {
  console.error(`TextReader failed to hide Minibar. Code: ${e.code}, message: ${e.message}`);
}

queryReadState

queryReadState(id?: string): ReadState

Queries the article reading status.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
id string No Article ID. The default value is the ID of the article that is being read.

Returns:

Type Description
ReadState Article reading status.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  let readState = TextReader.queryReadState('article_01');
  console.info(`Succeeded in querying read state, read state: ${JSON.stringify(readState)}`);
} catch (e) {
  console.error(`TextReader failed to queryReadState. Code: ${e.code}, message: ${e.message}`);
}

setArticleContent

setArticleContent(id: string, content?: string): void

Sets the article content.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
id string Yes Article ID.
content string No Article content. If content is not passed or is left empty, the control content page will show a loading failure message upon an attempt to play the article with the specified ID. If content is passed, it will be set to the content of the article with the specified ID.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
    TextReader.setArticleContent('article_01', '*Text body to read*');
} catch (e) {
  console.error(`TextReader failed to setArticleContent. Code: ${e.code}, message: ${e.message}`);
}

setArticle

setArticle(readInfo: ReadInfo): void

Sets the information about a specified article and plays the article immediately.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
readInfo ReadInfo Yes Article information. Only parameters image, imageUrl, bodyInfo, and bodyInfoObject need to be updated. If the article ID is not in the list, the article cannot be played.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';
import { image } from '@kit.ImageKit';

const readInfo: TextReader.ReadInfo = {
  id: '001',
  title: {
    text:'*Title of the text to read*',
    isClickable:true
  },
  author:{
    text:'*Author of the text to read*',
    isClickable:true
  },
  date: {
    text:'2024/01/01',
    isClickable:false
  },
  bodyInfo: '*Text body to read*'
  image: {} as image.PixelMap
};
try {
  TextReader.setArticle(readInfo);
} catch (e) {
  console.error(`TextReader failed to setArticle. Code: ${e.code}, message: ${e.message}`);
}

loadMore

loadMore(readInfos: ReadInfo[], isEnd: boolean): void

Loads more articles to the reading list. This API must be called after init and start are called in the project. You are advised to use this API in the 'requestMore' action listener.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
readInfos ReadInfo[] Yes List of articles to load.
isEnd boolean Yes

Indicates whether more content needs to be loaded.

- true: All content has been loaded.

- false: Some content is not completely loaded.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { ReadStateCode, TextReader, TextReaderIcon } from '@kit.SpeechKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {

  @State readInfoList: TextReader.ReadInfo[] = [];
  @State readState: ReadStateCode = ReadStateCode.WAITING;
  @State isInit: boolean = false;
  @State selectedReadInfo: TextReader.ReadInfo = this.readInfoList[0];
  aboutToAppear(){
    let context: Context | undefined = this.getUIContext().getHostContext();
    if (!context) {
      console.error(`context is undefined.`);
      return;
    }

    // Set reading parameters.
    const readerParams: TextReader.ReaderParam = {
      isVoiceBrandVisible: true,
      businessBrandInfo: {
        panelName: 'AI Reader',
        panelIcon: $r('app.media.startIcon')
      }
    };

    // Initialize the TextReader.
    TextReader.init(context, readerParams).then(() => {
      console.info(`TextReader succeeded in initializing.`);
    }).catch((e: BusinessError) => {
      console.error(`TextReader failed to initialize. Code: ${e.code}, message: ${e.message}`);
    })

    /**
     * Data loading
     */
    console.info(`ReadStateCode: ${JSON.stringify(this.readState)}`);
    let readInfoList: TextReader.ReadInfo[] = [{
      id: '001',
      title: {
        text:'*Title of the text to read*',
        isClickable:true
      },
      author:{
        text:'*Author of the text to read*',
        isClickable:true
      },
      date: {
        text:'2024/01/01',
        isClickable:false
      },
      bodyInfo: '*Text body to read*'
    }];
    this.readInfoList = readInfoList;
    this.selectedReadInfo = this.readInfoList[0];
  }

  // Set action listeners.
  setActionListener() {
    // ...
    TextReader.on('requestMore', () => {
      console.info(`requestMore`);
      try {
        console.info(`loadMore`);
        TextReader.loadMore(this.readInfoList, true);
      } catch (e) {
        console.error(`TextReader failed to loadMore. Code: ${e.code}, message: ${e.message}`);
      }
    });
  }


  build() {
    Column() {
      TextReaderIcon({ readState: this.readState })
        .margin({ right: 20 })
        .width(32)
        .height(32)
        .onClick(() => {
          try {
            this.setActionListener();
            void TextReader.start(this.readInfoList, this.selectedReadInfo?.id);
          } catch (e) {
            console.error(`TextReader failed to start`);
          }
        })
    }
    .height('100%')
  }
}

queryReadStateByCategoryId

queryReadStateByCategoryId(categoryId: string): ReadState

Queries the article status based on the category ID and checks whether the current category contains articles that are being played.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Parameter Type Mandatory Description
categoryId string Yes Category ID of the article that is being played.

Returns:

Type Description
ReadState Article reading status.

Error codes:

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

ID Error Message
401 Parameter error. 
import { TextReader } from '@kit.SpeechKit';

try {
  let readState = TextReader.queryReadStateByCategoryId('categoryId_01');
  console.info(`Succeeded in querying read state by category id, read state: ${JSON.stringify(readState)}`);
} catch (e) {
  console.error(`TextReader failed to queryReadStateByCategoryId. Code: ${e.code}, message: ${e.message}`);
}

on('setArticle')

on(type: 'setArticle', callback: Callback<string>): void

Registers an article setting callback, which will be triggered if the target article is empty (bodyInfo being empty) when an article is tapped or switched.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The 'setArticle' event type is supported and its callback will be triggered if the target article is empty (bodyInfo being empty) when an article is set.
callback Callback<string> Yes Callback executed when an article tap or switch event is triggered. The article id is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('setArticle', (id: string) => {
    console.info(`Succeeded in setting setArticleListener: ${id}`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('setArticle')

off(type: 'setArticle', callback?: Callback<string>): void

Unregisters a callback for article setting, and will be used after on(type: 'setArticle') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The 'setArticle' event type is supported and its callback will be triggered when an article is set.
callback Callback<string> No Callback executed to cancel the listening of the article tap or switch event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('setArticle');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('clickArticle')

on(type: 'clickArticle', callback: Callback<string>): void

Registers a callback for the tap event, which will be triggered when the title is tapped.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes

Event callback type. The supported event is 'clickArticle'. When an article title is tapped, the callback is triggered.
callback Callback<string> Yes Callback executed when the title tap event is triggered. The article id is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('clickArticle', (id: string) => {
    console.info(`Succeeded in setting clickArticleListener: ${id}`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('clickArticle')

off(type: 'clickArticle', callback?: Callback<string>): void

Unregisters a callback for the tap event, and will be used after on(type: 'clickArticle') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'clickArticle'. When an article title is tapped, the callback is canceled.
callback Callback<string> No Callback executed to cancel the listening of the title tap event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('clickArticle');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('clickAuthor')

on(type: 'clickAuthor', callback: Callback<string>): void

Registers a callback for the tap event, which will be triggered when the author is tapped.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'clickAuthor'. When an author is tapped, the callback is triggered.
callback Callback<string> Yes Callback executed when the author tap event is triggered. The article id is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('clickAuthor', (id: string) => {
    console.info(`Succeeded in setting clickAuthorListener: ${id}`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('clickAuthor')

off(type: 'clickAuthor', callback?: Callback<string>): void

Unregisters a callback for the tap event, and will be used after on('clickAuthor') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'clickAuthor'. When an author is tapped, the callback is canceled.
callback Callback<string> No Callback executed to cancel the listening of the author tap event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('clickAuthor');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on( 'clickNotification')

on(type: 'clickNotification', callback: Callback<string>): void

Registers a callback for the tap event. When the notification bar is tapped, the callback is triggered.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'clickNotification'. When a notification bar is tapped, the callback is triggered. Reserved parameter, which is not supported currently.
callback Callback<string> Yes Callback executed when the notification bar tap event is triggered. The article id is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('clickNotification', (id: string) => {
    console.info(`Succeeded in setting clickNotificationListener: ${id}`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('clickNotification')

off(type: 'clickNotification', callback?: Callback<string>): void

Unregisters a callback for the tap event, and will be used after on(type: 'clickNotification') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'clickNotification'. When a notification bar is tapped, the callback is canceled.
callback Callback<string> No Callback executed to cancel the listening of the notification bar tap event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('clickNotification');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('showPanel')

on(type: 'showPanel', callback: Callback<void>): void

Registers a callback for showing the playback panel, which will be triggered when the playback panel is shown.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'showPanel', which will be triggered when the playback panel is shown.
callback Callback<void> Yes Callback executed when the event of showing the panel is triggered. No result is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('showPanel', () => {
    console.info(`Succeeded in setting showPanelListener.`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('showPanel')

off(type: 'showPanel', callback?: Callback<void>): void

Unregisters a callback for showing the playback panel, and will be used after on(type: 'showPanel') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'showPanel', which will not be triggered when the playback panel is shown.
callback Callback<void> No Callback executed to cancel the listening of the panel showing event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('showPanel');
  TextReader.off('hidePanel');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('hidePanel')

on(type: 'hidePanel', callback: Callback<void>): void

Registers a callback for hiding the playback panel, which will be triggered when the playback panel is hidden.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'hidePanel', which will be triggered when the playback panel is hidden.
callback Callback<void> Yes Callback executed when the event of hiding the panel is triggered. No result is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('hidePanel', () => {
    console.info(`Succeeded in setting hidePanelListener.`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('hidePanel')

off(type: 'hidePanel', callback?: Callback<void>): void

Unregisters a callback for hiding the playback panel, and will be used after on(type: 'hidePanel') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'hidePanel', which will not be triggered when the playback panel is hidden.
callback Callback<void> No Callback executed to cancel the listening of the panel hiding event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('showPanel');
  TextReader.off('hidePanel');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('stop')

on(type: 'stop', callback: Callback<void>): void

Registers a callback for the stop event, which will be triggered when the stop API is called.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is stop, which is triggered when the stop API is called or a user swipes the notification bar to exit.
callback Callback<void> Yes Callback executed when the stop event is triggered. No result is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('stop', () => {
    console.info(`Succeeded in setting stopListener.`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('stop')

off(type: 'stop', callback?: Callback<void>): void

Unregisters a callback for the stop event, and will be used after on(type: 'stop') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is stop, which is triggered when the stop API is called or a user swipes the notification bar to exit.
callback Callback<void> No Callback executed to cancel the listening of the stop event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('stop');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('release')

on(type:'release', callback: Callback<void>): void

Registers a callback for the release event, which will be triggered when the release API is called.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'release', which is called to release resources.
callback Callback<void> Yes Callback executed when the release event is triggered. No result is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('release', () => {
    console.info(`Succeeded in setting releaseListener.`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('release')

off(type: 'release', callback?: Callback<void>): void

Unregisters a callback for the release event, and will be used after on(type: 'release') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'release', which is called to release resources.
callback Callback<void> No Callback executed to cancel the listening of the release event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('release');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('stateChange')

on(type: 'stateChange', callback: Callback<ReadState>): void

Registers a callback for the status change event, which will be triggered when the status of the article that is being played changes.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The 'stateChange' event type is supported and its callback will be triggered when the status of the article that is being played changes.
callback Callback<ReadState> Yes Callback executed when the status of the article that is being played changes. ReadState is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('stateChange', (state: TextReader.ReadState) => {
    console.info(`Succeeded in setting stateChangeListener: ${JSON.stringify(state)}`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('stateChange')

off(type: 'stateChange', callback?: Callback<ReadState>): void

Unregisters a callback for the article (that is being played) status change event, and will be used after on(type: 'stateChange') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The 'stateChange' event type is supported and its callback will be triggered when the status of the article that is being played changes.
callback Callback<ReadState> No Callback executed to cancel the listening to the status change of the article that is being played. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('stateChange');
} catch (e) {
  console.error(`TextReader failed to unset stateChange eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('requestMore')

on(type: 'requestMore', callback: Callback<void>): void

Registers a callback for the event of requesting more articles, which will be triggered when the reading list is swiped to the bottom or the last article is played.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The 'requestMore' event type is supported and its callback will be triggered when more articles are requested.
callback Callback<void> Yes Callback executed when the reading list is swiped to the bottom or the last article is played. No result is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('requestMore', () => {
    console.info(`Succeeded in setting requestMoreListener.`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('requestMore')

on(type: 'requestMore', callback: Callback<string>): void

Registers a callback for the event of requesting more articles, which will be triggered when the reading list is swiped to the bottom or the last article is played. User-defined parameters will be returned through the callback.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The 'requestMore' event type is supported and its callback will be triggered when the reading list is swiped to the bottom and more articles are requested.
callback Callback<string> Yes Callback executed when the reading list is swiped to the bottom or the last article is played. The return result is the custom parameter string configured in StartParams.callbackParam.

Error codes:

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

ID Error Message
401 Parameter error. 
import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('requestMore', (callback) => {
    console.info(`Succeeded in setting requestMoreListener. Callback is ${callback}`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('requestMore')

off(type: 'requestMore', callback?: Callback<void>): void

Unregisters a callback for the event of swiping the reading list to the bottom or playing the last article, and will be used after on(type: 'requestMore') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The 'requestMore' event type is supported and its callback will be triggered when more articles are requested.
callback Callback<void> No Callback executed to cancel the listening to the event of reaching the bottom of the reading list or the last article. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('requestMore');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('requestMore')

off(type: 'requestMore', callback: Callback<string>): void

Unregisters a callback (with user-defined parameters passed) for the event of swiping the reading list to the bottom or playing the last article, and will be used after on(type: 'requestMore') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.3(15)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The 'requestMore' event type is supported and its callback will be triggered when more articles are requested.
callback Callback<string> Yes Callback executed to cancel the listening to the event of reaching the bottom of the reading list or the last article. The callback must be the same as that passed during subscription.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('requestMore', (callback:string) => {
    console.info(`Succeeded in setting requestMoreListener. Callback is ${callback}`);
  });
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('eventNotification')

on(type: 'eventNotification' , callback: Callback<NotificationEvent>): void

Registers a callback for the media controller status change event, which will be triggered when the status of the media controller status changes.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'eventNotification', which is triggered when the status of the media controller changes.
callback Callback<NotificationEvent> Yes Callback executed when the status of the media controller changes. NotificationEvent is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('eventNotification', (ne: TextReader.NotificationEvent) => {
    console.info(`Succeeded in setting eventNotificationListener: ${JSON.stringify(ne)}`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('eventNotification')

off(type: 'eventNotification', callback?: Callback<NotificationEvent>): void

Unregisters a callback for the media controller status change event, and will be used after on(type: 'eventNotification') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Defines the event callback type. Event callback type. The supported event is 'eventNotification', which is used to deregister the event.
callback Callback<NotificationEvent> No Callback executed to cancel the listening to the status change event of the media controller. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('eventNotification');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('eventPanel')

on(type: 'eventPanel', callback: Callback<PanelEvent>): void

Registers a callback for the playback panel status change event, which will be triggered when the status of the playback panel status changes.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'eventPanel', indicating the playback panel status change. The BPC_10 click event callback in PanelEvent is supported only on mobile phones.
callback Callback<PanelEvent> Yes Callback executed when the playback panel status changes. PanelEvent is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('eventPanel', (pe: TextReader.PanelEvent) => {
    console.info(`Succeeded in setting eventPanelListener: ${JSON.stringify(pe)}`);
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('eventPanel')

off(type: 'eventPanel', callback?: Callback<PanelEvent>): void

Unregisters a callback for the playback panel status change event, and will be used after on(type: 'eventPanel') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'eventPanel', indicating the playback panel status change.
callback Callback<PanelEvent> No Callback executed to cancel the listening to the panel status change event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('eventNotification');
  TextReader.off('eventPanel');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on( 'eventReadList')

on(type: 'eventReadList', callback: Callback<Array<ListEventState>>): void

Registers a callback for the reading list event, which will be triggered when the reading list icon is tapped.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'eventReadList'.
callback Callback<Array<ListEventState>> Yes Callback executed when the reading list icon tap event is triggered. ListEventState is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('eventReadList', (list: Array<TextReader.ListEventState>) => {
    list.forEach((id) => {
      console.info(`Succeeded in setting eventReadListListener, article id: ${id}`);
    });
  });
} catch (e) {
  console.error(`TextReader failed to set eventListener. Code: ${e.code}, message: ${e.message}`);
}

off('eventReadList')

off(type: 'eventReadList', callback?: Callback<Array<ListEventState>>): void

Unregisters a callback for the reading list event, and will be used after on(type: 'eventReadList') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'eventReadList'.
callback Callback<Array<ListEventState>> No Callback executed to cancel the listening of the reading list icon tap event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('eventReadList');
} catch (e) {
  console.error(`TextReader failed to unset eventListener. Code: ${e.code}, message: ${e.message}`);
}

on('readProgress')

on(type: 'readProgress', callback: Callback<ReadProgress>): void

Registers a callback for the playback progress event, which will be triggered when an interaction related to the playback progress occurs, for example, when the playback is paused, stopped, or completed, or when the scheduled operation specified by reportProgressPeriod in ReaderParam is initialized.

Note: When multiple callbacks are registered for the same event, only the first one takes effect. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'readProgress'.
callback Callback<ReadProgress> Yes Callback executed when the playback progress change event is triggered. ReadProgress is returned.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.on('readProgress', (readProgress: TextReader.ReadProgress) => {
    console.info(`Succeeded in setting readProgressListener: ${JSON.stringify(readProgress)}`);
  });
} catch (e) {
  console.error(`TextReader failed to set readProgressListener. Code: ${e.code}, message: ${e.message}`);
}

off('readProgress')

off(type: 'readProgress', callback?: Callback<ReadProgress>): void

Unregisters a callback for the playback progress event, and will be used after on(type: 'readProgress') is called. You can register a new callback after the current one is unregistered. This API returns the result asynchronously through a callback.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Parameter Type Mandatory Description
type string Yes Event callback type. The supported event is 'readProgress'.
callback Callback<ReadProgress> No Callback executed to cancel the listening to the playback progress change event. The callback must be the same as that passed during subscription. If this parameter is not specified, all callbacks used by the current app to listen to the event are canceled.

Error codes:

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

ID Error Message
401 Parameter error.

Example:

import { TextReader } from '@kit.SpeechKit';

try {
  TextReader.off('readProgress');
} catch (e) {
  console.error(`TextReader failed to unset readProgressListener. Code: ${e.code}, message: ${e.message}`);
}

Person

Tone and style of a person.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Name Type Read-Only Optional Description
tone number No No

Tone of a person.

0: female
style string No No

Style of a person.

- reading: reading style (not supported currently)

- interaction-oral: oral style (not supported currently)

-interaction-broadcast: broadcast style

ReaderParam

Reading parameters.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Name Type Read-Only Optional Description
isVoiceBrandVisible boolean No No

Indicates whether to display the brand.

- false (default): no

- true: yes
businessBrandInfo BusinessBrandInfo No Yes

Brand information.

- AI Reader is used by default.
isFastForward boolean No Yes

Fast-forward and rewind logic.

- false (default): by sentence

- true: by 15 seconds
keepBackgroundRunning boolean No Yes

Indicates whether the control keeps running in the background.

Reserved parameter, which is not supported currently.

- false (default): no

- true: The long-duration task permission needs to be configured. For details, see step 9 in the development guide.
online number No Yes

Synthesis mode. The offline synthesis mode is used by default.

0: online (not supported currently); 1: offline
person Person No Yes

Tone and style of the speaker. The default settings are as follows:

{ tone: 0, style: 'interaction-broadcast' }

Since: 5.0.2(14)
isMinibarNeeded boolean No Yes

Indicates whether to use the minibar function.

-true (default): yes

- false: no. In this case, the hideMinibar and showMinibar methods cannot take effect.

Since: 5.0.2(14)
minibarParams MinibarParams No Yes

Minibar position setting. By default, it is set to attach to the left.

Since: 5.0.2(14)
customFeatures CustomFeature[] No Yes

Custom features of the TextReader. The parameter is empty by default.

Since: 5.0.2(14)
displayTab DisplayTab No Yes

Tab page display configuration. By default, the cover and content pages are displayed.

Since: 5.0.2(14)

Device behavior differences: This API has no effect on PCs/2-in-1 devices, but works properly on other devices.
reportProgressPeriod number No Yes

Interval for returning the playback duration log information. The default value is 0, indicating that the playback duration log information is not returned.

Unit: ms.

Since: 5.0.2(14)

StartParams

Playback start parameters of the TextReader.

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Name Type Read-Only Optional Description
isMinibarHidden boolean No Yes

Indicates whether to hide the minibar.

- false (default): no

- true: yes

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
callbackParam string No Yes

Scene parameter that you can define, which will be returned through the callback for the requestMore event. It is empty by default.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
startPercent number No Yes

Start position of the playback. The value ranges from 0 to 100. The default value is 0.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

Since: 6.0.1(21)

MinibarParams

Parameters for controlling the minibar during playback startup. You can set the initial position of the minibar and the distance between the minibar and the bottom edge.

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Name Type Read-Only Optional Description
defaultAlignment BarAlignment No No

Default attaching position of the minibar.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
bottom number No Yes

Distance between the minibar and the bottom edge. You can only drag the minibar leftward or rightward, not vertically.

The value must be greater than or equal to 0. The default value is 50, in vp. The minibar will not be displayed if its position exceeds the screen area.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
isSpeedIconVisible boolean No Yes

Indicates whether the minibar displays the playback speed control button.

The default value true indicates yes.

The value false indicates no.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

Since: 6.0.1(21)
isNextIconVisible boolean No Yes

Indicates whether the minibar displays the next article button.

The value true indicates yes.

The default value false indicates no.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

Since: 6.0.1(21)

BusinessBrandInfo

Brand information.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Name Type Read-Only Optional Description
panelName string No Yes

- Service name displayed on the top of the playback panel. Based on the normal system font size, each English character counts as one character and each Chinese character counts as two characters. If the total length exceeds 24 characters, the exceeding part will not be displayed. (The display length changes when the system font size changes.)

- When the aspect ratio of a device is greater than 1.5 and less than 2, or the width and height are equal, and the device is folded, the brand information will not be displayed.
panelIcon ResourceStr No Yes

Service icon displayed on the top of the playback panel.

Reserved parameter, which is not supported currently.
notificationIcon ResourceStr No Yes

Service icon displayed on the notification bar.

Reserved parameter, which is not supported currently.
notificationName string No Yes

Service name displayed on the notification bar.

Reserved parameter, which is not supported currently.

ReadState

Reading status.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Name Type Read-Only Optional Description
id string No No Article ID.
state ReadStateCode No No Current reading status.
categoryId string No Yes

Article category ID.

Since: 5.0.2(14)
isLastArticle boolean No Yes

Playback by category:

Indicates whether the article being played is the last article in the category. true: yes;

false: no.

Playback not by category:

Indicates whether the article being played is the last article in the list. true: yes;

false: no.

Since: 5.0.2(14)

CustomFeature

Custom features on the TextReader panel.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Name Type Read-Only Optional Description
type CustomFeatureType No No Type of a custom feature. A custom feature can be defined by a system app or user.
name string No No

Name of a custom feature.

When type is set to CustomFeatureType.SYSTEM, options for the supported system features include:

- favorite (adding to favorites)

- countdown (timer)
icon ResourceStr No Yes

Icon of a custom feature, supporting formats such as URLs and local resources.

The value is empty by default.

When type is set to CustomFeatureType.SYSTEM, the icon for the system feature is fixed and does not need to be specified.
callback Callback<string> No Yes Callback of a custom feature. The callback parameter is the ID of the article that is being played.

Example:

import { TextReader } from '@kit.SpeechKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  // Obtain the application context.
  aboutToAppear() {
    const customFeaturesToAdd: TextReader.CustomFeature[] = [
      {
        type: TextReader.CustomFeatureType.SYSTEM,
        name: 'countdown',
        icon: '',
        callback: (id) => {
          console.info(`Custom feature callback.`);
        }
      }
    ];
    const readerParams: TextReader.ReaderParam = {
      // Other field configurations.
      customFeatures: customFeaturesToAdd,
      isVoiceBrandVisible: false
    };
    let context: Context | undefined = this.getUIContext().getHostContext();
    if (context) {
      TextReader.init(context, readerParams).then(() => {
        console.info(`TextReader succeeded in initializing.`);
      }).catch((e: BusinessError) => {
        console.error(`TextReader failed to initialize. Code: ${e.code}, message: ${e.message}`);
      });
    }
  }

  build() {
    // ...
  }
}

ReadInfo

Reading information.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Name Type Read-Only Optional Description
id string No No Article ID, which cannot be an empty string.
title TextInfo No No Title.
category string No Yes Category, which is empty by default.
author TextInfo No Yes Author of an article, which is empty by default.
date TextInfo No Yes

Time of an article. Example: Mon Jul 08 2024 21:25:41 GMT+0800.

Reserved parameter, which is not supported currently.
image image.PixelMap No Yes

Cover image. The maximum size of the image after being converted into PixelMap is 8 MB.

If this parameter is not passed, the default cover image will be used.
imageUrl string No Yes

URL of the article cover image.

If this parameter is not passed, the default cover image will be used. If the image dimensions (width \× height) exceed 1024 \× 2048, the image will be compressed.

When both image and imageUrl are passed, the image parameter takes effect.

Since: 5.0.2(14)
bodyInfo string No Yes

This parameter is mandatory for the setArticle and loadMore APIs.

Body information for real-time reading.

For 6.0.2(22) and earlier versions, if the body does not contain punctuations or newline characters, its length must be less than or equal to 10,000 characters. For 6.1.0(23) and later versions, the body can contain more than 10,000 characters.
bodyInfoObject BodyInfo No Yes

Body content information, which is empty by default. The difference between bodyInfo and bodyInfoObject is that bodyInfo only updates the content, while bodyInfoObject updates the article content, cover image, and article title. If both are assigned values, bodyInfoObject takes effect.

Since: 5.0.2(14)
categoryObject CategoryInfo No Yes

Article category information, which is empty by default.

Since: 5.0.2(14)
audioInfo AudioInfo[] No Yes

Audio information, which is empty by default.

If this parameter is set, the corresponding audio will be preferentially used for playback.

Since: 5.0.2(14)
isFavorite boolean No Yes

Indicates whether the article has been liked or added to favorites. true: yes;

false: no.

The default value is false.

Since: 5.0.2(14)

CategoryInfo

Article category information.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Name Type Read-Only Optional Description
id string No No Article category ID.
name string No No Article category name.
image PixelMap | string No No

Image or image URL of the article category.

When an image is displayed on the reading details page or minibar floating window, the article category image has a higher priority than the article cover image.

TextInfo

Text information.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Name Type Read-Only Optional Description
text string No No Text.
isClickable boolean No No

Indicates whether the playback panel can be hidden through tapping.

- true: yes

- false: no

BodyInfo

Body content of readInfo.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Name Type Read-Only Optional Description
type BodyInfoType No No Type.
body string No Yes Body content, which is empty by default.

AudioInfo

Audio information in the TextReader.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Name Type Read-Only Optional Description
format string No No Audio format. For example, MP3, MP4A, WMA, and WAV.
duration number No No Audio duration, in seconds.
size(deprecated) number No No

Audio information size, in bytes.

NOTE

This parameter has been deprecated since 6.1.0(23).
person Person No Yes

Audio characteristics, including the timbre and style.

The default values are as follows:

{ tone: 3, style: 'interaction-broadcast' }
url string No No URL of an audio.

ReadProgress

Reading progress information in the TextReader.

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Parameters

Name Type Read-Only Optional Description
id string No No

ID of the article that is being played.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
categoryId string No No

Article category ID.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
readProgressType ReadProgressType No No

Periodical report type.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
person Person No No

Timbre used for the article being played.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
maxPercent number No No

Maximum playback percentage that the user has reached when this event callback is triggered, rather than the current playback percentage.

Value range: [0,100]

[Calculation method]

Maximum percentage of audio playback progress, which is rounded to the nearest whole percent. For example, when the audio playback progress has reached 80% and the user reverted the play bar to 20% and then stopped the playback, it would be reported as 80.

The value will be reset during replay.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).
currentPercent number No No

Current playback percentage of the user when this event callback is triggered. The value ranges from 0 to 100. It can be used to record the last playback position and, together with the start API, resume playback from where the user left off.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

Since: 6.0.1(21)

PanelEvent

Playback panel event.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Name Type Read-Only Optional Description
id string No No Article ID.
click string No No

- BPC_01: tapping the playback button

- BPC_02: tapping the pause button

- BPC_03: tapping the previous button

- BPC_04: tapping the next button

- BPC_05: tapping the speed button

- BPC_06: tapping the timbre button

- BPC_07: tapping the reading list

- BPC_08: tapping the title

- BPC_09: tapping the author

- BPC_10: exiting the panel by tapping the arrow in the upper left corner or swiping down
categoryId string No Yes

Article category ID.

Since: 5.0.2(14)

NotificationEvent

Notification bar event.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Name Type Read-Only Optional Description
id string No No Article ID.
type number No No

1: notification bar tap callback

2: media controller tap callback
click string No No

- NBC_01: tapping the playback button

- NBC_02: tapping the pause button or removing the media controller from the notification bar

- NBC_03: tapping the close button (reserved and not supported for now)

- NBC_04: tapping the previous button

- NBC_05: tapping the next button

- NBC_06: tapping an image in an article (reserved)

- NBC_07: tapping the title of an article (reserved)
categoryId string No Yes

Article category ID.

Since: 5.0.2(14)

ListEventState

List event status.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.0(12)

Parameters

Name Type Read-Only Optional Description
id string No No Article ID.
categoryId string No Yes

Article category ID.

Since: 5.0.2(14)

ResetParamType

Enumeration class used to determine the reset type.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Name Value Description
BAR_PARAM 1 Minibar parameters.
ALL 2 All local data, including minibar parameters and the article list.
READ_LIST 3 Article list.

DisplayTab

Enumeration class used to determine the tabs displayed on the playback panel and their content.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Device behavior differences: This API has no effect on PCs/2-in-1 devices, but works properly on other devices.

Since: 5.0.2(14)

Name Value Description
COVER_AND_CONTENT 1 Cover page and content page, with the tab button displayed.
CONTENT 2 Only the content page. The tab button is not displayed.
COVER 3 Only the cover page. The tab button is not displayed.

BarAlignment

Enumeration class used to determine the default attaching position of the minibar.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Name Value Description
LEFT 1 Attached to the left.
RIGHT 2 Attached to the right.

BodyInfoType

Enumeration class used to determine the type of body information.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Name Value Description
CONTENT 1 Body content.
FILE_PATH 2 File path.

CustomFeatureType

Enumeration class used to determine the type of a custom feature.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Name Value Description
SYSTEM 1 System-defined features.
USER 2 User-defined features.

ReadProgressType

Enumeration class used to determine the type for reporting the playback progress.

Atomic service API: This API can be used in atomic services since version 5.0.3(15).

System capability: SystemCapability.AI.Component.TextReader

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

Since: 5.0.2(14)

Name Value Description
PROGRESS 1 Reported periodically during playback.
PAUSE 2 Reported when the playback is paused.
STOP 3 Reported when the playback is stopped.
COMPLETED 4 Reported when the article is read completely.