*Mandatory. Describe basic concepts related to a development task to help developers better understand the task. The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.*
| Requirement| Satisfied or Not|
| -------- | -------- |
| Common concepts in the industry are not described.| |
| Common terms in the industry, rather than internal terms, are used.| |
***[Example]***
The XX system provides the audio module for your application to implement audio-related features, including audio playback, recording, and volume management.
It is considered good practice that you understand the following concepts before starting application development:
- Sampling
Sampling is a process where analog signals are converted into digital signals that can be represented by 0101.
- Sampling rate
Sampling rate is the number of samples extracted from a continuous signal per second to form a discrete signal. It is measured in Hz. Generally, human hearing range is from 20 Hz to 20 kHz. Common audio sampling rates include 8 kHz, 11.025 kHz, 22.05 kHz, 16 kHz, 37.8 kHz, 44.1 kHz, 48 kHz, 96 kHz, and 192 kHz.
- Channel
Channels refer to different spatial positions where independent audio signals are recorded or played. The number of channels is the number of audio sources used during audio recording, or the number of speakers used for audio playback.
- Audio frame
Audio data is in stream form. For the convenience of audio algorithm processing and transmission, it is generally agreed that a data amount in a unit of 2.5 to 60 milliseconds is one audio frame. This unit is called sampling time, and its length is specific to codecs and the application requirements.
## Working Principles
***[Writing Requirements]***
*Optional. You can delete this section if the working principles are simple and the basic concepts in the **Overview** section are enough for understanding.*
*Describe the implementation principles, for example, the time for calling the APIs and triggering callbacks related to key steps, to help developers better understand the basic operation principles, carry out development tasks, and locate problems.*
*The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.*
| Requirement| Satisfied or Not|
| -------- | -------- |
| Only principles related to the development task are described.| |
| Supplementary graphics are used, such as sequence diagrams and flowcharts. The text description is consistent with the figure description.| |
***[Example 1]***
- Semaphore initialization: The system allocates memory for the semaphores configured (the value of *N* can be configured by users and is limited by the memory), initializes all semaphores to be unused semaphores, and adds them to a linked list for the system to use.
- Semaphore creation: The system obtains a semaphore from the linked list of unused semaphores and assigns an initial value to the semaphore.
- Semaphore request: If the counter value is greater than 0, the system allocates a semaphore, decreases the value by 1, and returns a success message. Otherwise, the system blocks the task and adds the task to the end of a task queue waiting for semaphores. The wait timeout period can be set.
- When a semaphore is released, if there is no task waiting for it, the counter is increased by 1. Otherwise, the first task in the wait queue is woken up.
- Semaphore deletion: The system sets a semaphore in use to the unused state and inserts it to the linked list of unused semaphores.
- Semaphore allows only a specified number of tasks to access a shared resource at a time. When the number of tasks accessing the resource reaches the limit, other tasks will be blocked until the semaphore is released.
***[Example 2]***
**Working Principles of Mutexes**
In a multi-task environment, multiple tasks may access the same shared resource. However, certain shared resources are not shared, and can only be accessed exclusively by tasks. A mutex can be used to address this issue.
When non-shared resources are accessed by a task, the mutex is locked. Other tasks will be blocked until the mutex is released by the task. The mutex allows only one task to access the shared resources at a time, ensuring integrity of operations on the shared resources.
## Limitations and Constraints
***[Writing Requirements]***
*Mandatory. Describe the constraints of the development task and the negative impact of the constraints, including but not limited to the following:*
-***Function Limitations***
-*Application scope of the function (specify scenarios that are not supported)*
-*Specification limitations*
-***Operation Limitations***
-*Operations on known issues*
-*Potentially risky operations (such as performance deterioration)*
-*Operations that may cause performance deterioration*
*The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.*
| Requirement| Satisfied or Not|
| -------- | -------- |
| The function limitations or operation restrictions are clearly specified.| |
| Only constraints that affect task development or user experience are described.| |
| Operations that are prone to errors are described in the procedure but not described in this section.| |
***[Example]***
**Limitations and Constraints on Mutexes:**
- Two tasks cannot lock the same mutex. If a task attempts to lock a mutex held by another task, the task will be blocked until the mutex is unlocked.
- Mutexes cannot be used in the interrupt service program.
- When using the LiteOS-A kernel, the xx system must ensure real-time task scheduling and avoid long-time task blocking. Therefore, a mutex must be released as soon as possible.
- When a mutex is held by a task, the task priority cannot be changed by using APIs such as **LOS_TaskPriSet**.
> *1. This template provides the recommended development guide document framework and writing instructions for typical knowledge points. In your writing, complete the development task scenario analysis and development guide outline design based on the specific **solution/feature/function/module**, and then write the content based on this template.*
>
> *2. Do not add any content between level-1 title (marked with #) and level-2 title (marked with ##).*
>
> *3. Delete all the writing instructions in italics from your formal documents.*
## *Example* Overview
*Mandatory. Based on the scenario division of the solution/feature/function/module, you need to provide either "Example Overview" or "Example Task Scenario Overview", or both of them.*
*1. "Example Overview" provides an overview that is common to all task scenarios of this solution/feature/function/module and that developers need to understand. If there is nothing in common, delete it.*
*2. "Example Task Scenario Overview" describes the contents directly related to a task scenario. The knowledge points and key writing points are the same as those in "Example Overview". In this section, you need to introduce this specific task scenario and describe basic concepts, working principles, constraints, and samples that are directly related to the task scenario. If there is no specific task scenario, delete it.*
***[General Instructions for Writing the Development Guide]***
***1. Target audience**: internal and external developers (including product managers). Guidelines for UX designers are usually carried by UX design specifications and are not covered in the development guide. If UX design specifications need to be mentioned in the development guide, use hyperlinks.*
***2. Content positioning**: Introduce what the solution/feature/function/module is, why it is required, and how to design, develop, and release related applications/devices. The development guide aims to help developers learn necessary knowledge and achieve specified task objectives in actual development activities.*
***3. User-oriented****: Always provide developer-concerned, perceptible, and useful content from the perspective of developers.*
*Mandatory. Describe how a developer completes tasks in a specific scenario. Include one scenario in each section. The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.*
***4. Task-oriented****: Focus on actual tasks of developers, and provide complete, correct guidance that is easy to follow.*
*5. This template only provides the basic document framework. You can adjust the content based on the actual requirements.*
| Requirement| Satisfied or Not|
| -------- | -------- |
| Each section covers only one scenario. If there are multiple scenarios, provide development guidelines for each scenario in separate sections. For example, you can use the following sections in **Audio**: **Development Guidelines on Audio Playback**, **Development Guidelines on Volume Management**, and **Development Guidelines on Sound Playback**.| |
| Use verbs + nouns to describe task operations in titles.| |
### Introduction
## When to Use
*Mandatory.*
***[Developers' Concerns]***
*What is the solution/feature/function/module (definition)? What problems can it solve or what benefits can it bring (purpose/customer benefits - why)? *
***[Key Writing Points]***
-*Provide easy-to-understand and scenario-specific descriptions. Refer to the SCQA method below to introduce the scenarios and characteristics of the solution/feature/function/module.*
-*S: situation. Introduce a familiar scenario.*
-*C: complication. Describe the conflict between the situation and requirement.*
-*Q: question. Ask a question. What can I do in such a case?*
-*A: answer. Describe the solution.*
-*Visualize abstract concepts. You can provide content from the perspective of consumers for better understanding, for example, scenario effect in UX.*
***[Writing Requirements]***
*Mandatory. Describe in which scenario, what problem is solved, and what the final effect is. Use the SCQA method.*
-*Provide clear content. Avoid vague, obscure, and ambiguous expressions.*
-*Use only necessary terms, acronyms, abbreviations, and proper nouns, and provide explanations or links to the glossary.*
-*Use consistent terms, acronyms, abbreviations, and proper nouns throughout the document.*
### Basic Concepts
-*S: situation. Introduce a familiar scenario.*
*Optional. Describe the basic concepts that are common to all task scenarios.*
-*C: complication. Describe the conflict between the situation and requirement.*
***[Developers' Concerns]***
-*Q: question. Ask a question. What can I do in such a case?*
*What are the unique concepts that I need to know when using the solution/feature/function/module?*
-*A: answer. Describe the solution.*
***[Key Writing Points]***
*The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.*
-*Provide only the concepts that are mandatory in development tasks.*
| Requirement| Satisfied or Not|
| -------- | -------- |
| Clearly describe the background, what operations are done when and where, what problems are solved, and what benefits are delivered.| |
-*Describe here concepts used in multiple chapters such as the operation mechanism, restrictions, and development process. If a concept is used only in a chapter, describe the concept in that chapter only.*
-*Do not describe common concepts in the industry. Use common terms in the industry instead of jargon.*
-*If there are logical relationships between concepts, you are advised to use figures to describe the relationships.*
***[Writing Requirements]***
-*Provide clear content. Avoid vague, obscure, and ambiguous expressions.*
-*Use only necessary terms, acronyms, abbreviations, and proper nouns, and provide explanations or links to the glossary.*
-*Use consistent terms, acronyms, abbreviations, and proper nouns throughout the document.*
***[Example]***
You can use APIs described in this section to convert audio data into audible analog signals, play the audio signals using output devices, and manage playback tasks.
Before developing relational databases, you must understand the following basic concepts:
-**RDB**
A type of database based on the relational model of data. The RDB stores data in rows and columns. An RDB is also called RDB store.
-**Predicate**
Property or feature of a data entity, or the relationship between data entities. It is mainly used to define operation conditions.
-**Result set**
A set of query results used to access the data. You can access the required data in a result set in flexible modes.
### Working Principles
*Optional. Describe the working principles that are common to all task scenarios.*
***[Developers' Concerns]***
*How does the solution/feature/function/module work? What are the API calling and triggering time of key steps? I want to understand its principles for better use and debugging.*
***[Key Writing Points]***
-*If the principle is simple and can be understood from the content under "Basic Concepts", do not provide this section.*
## Available APIs
-*Describe only the mechanisms and principles that are visible in the development tasks (use or access). Do not provide internal implementation that is invisible to developers.*
-*If necessary, use sequence diagrams and flowcharts. Ensure that the text description matches the figure description.*
-*Be careful not to disclose internal information.*
***[Writing Requirements]***
*Mandatory. Describe APIs involved in the development guideline to help developers have a general understanding of the APIs, thereby improving development efficiency. The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.*
-*Provide clear content. Avoid vague, obscure, and ambiguous expressions.*
-*Use only necessary terms, acronyms, abbreviations, and proper nouns, and provide explanations or links to the glossary.*
-*Use consistent terms, acronyms, abbreviations, and proper nouns throughout the document.*
***[Example]***
The distributed data objects are encapsulated into JS objects in distributed in-memory databases, which allows the distributed data objects to be operated in the same way as local variables. The system automatically implements cross-device data synchronization.
*Optional. Describe constraints that are common to all task scenarios.*
***[Developers' Concerns]***
*What are the constraints for using the solution/feature/function/module? How well is the solution/feature/function/module implemented? Can it meet my requirements?*
***[Key Writing Points]***
-*Describe perceptible constraints that affect development activities, including but not limited to the following:*
-***Function constraints***
-*Application scope of the solution/feature/function/module (Specify scenarios that are not supported.)*
-*Specification constraints*
-***Operation constraints***
-*Operations on known issues*
-*Potentially risky operations (such as performance deterioration)*
-*Describe operations that are prone to errors in the procedure, but not in this section.*
***[Example]***
- Data synchronization can be implemented across devices only for the applications with the same bundleName.
- Each distributed data object occupies 100 KB to 150 KB of memory. Therefore, you are advised not to create too many distributed data objects.
- The maximum size of a distributed data object is 500 KB.
### Samples
| Requirement| Satisfied or Not|
| -------- | -------- |
| Include only APIs relevant to the development task.| |
| If there are more than 10 APIs, you can provide only main APIs.| |
*Optional. Provide samples that are common to all task scenarios.*
***[Developers' Concerns]***
*What sample code, codelabs, and demo projects are available?*
***[Key Writing Points]***
*Provide links (generally Gitee links) to the released sample code, codelabs, and demo projects. Do not include project packages into the document as an attachment.*
***[Example]***
The **AudioRenderer** class provides open audio playback capabilities. For details about the APIs, see the API reference.
The following sample is provided to help you better understand how to develop abilities:
-[Intra- and Inter-page Navigation](https://gitee.com/openharmony/codelabs/tree/master/Ability/PageAbility)
**Table 1** Audio playback APIs
| API| Description|
| -------- | -------- |
| AudioRenderer(AudioRendererInfo audioRendererInfo, PlayMode pm) throws IllegalArgumentException | A constructor used to create an **AudioRenderer** instance based on the specified playback parameters, the specified playback mode, and the default playback device.|
| AudioRenderer(AudioRendererInfo audioRendererInfo, PlayMode pm, AudioDeviceDescriptor outputDevice) throws IllegalArgumentException | A constructor used to create an **AudioRenderer** instance based on the specified playback parameters, playback mode, and playback device.|
| boolean play() | Plays audio streams.|
| boolean write(byte[] data, int offset, int size) | Writes audio data in the specified byte array into an audio receiver for playback.|
## Setting Up the Environment
*Optional.*
## How to Develop
*Based on the analysis and breakdown of a specific task scenario, you can place the environment setup content under "Prerequisites" or "Preparations" and close to the "How to Develop" of the specific scenario.*
*Specify how to prepare the development environment, including software and hardware configuration requirements, tool requirements, and device requirements.*
*Delete this section if no special requirements are involved.*
### Environment Requirements
***[Writing Requirements]***
*Mandatory. Describe the overall process to help developers quickly complete the task. The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.*
| Requirement| Satisfied or Not|
| -------- | -------- |
| **Writing a Development Procedure**| |
| Complete: All mandatory steps are provided.| |
| Clear: The logic of the writing is clear and reasonable. The overview, preparations, and operations in the document are described by following certain logic, and the chapters are not broken or contradictory.| |
| Sentence pattern for tasks: Use verbs + nouns to describe actions in titles or sentences.| |
| Prevention in advance: Describe the restrictions, error-prone operations, and potential risks in advance. Use general icons and styles.| |
| Clear steps-1: Describe the purpose of each step, no matter whether it is simple or not.| |
| Clear steps-2: Specify the environment, tools, operations, and how-to.| |
| If an operation is optional, specify the optional conditions.| |
| After the development procedure is complete, specify the expected results.| |
| **Writing a Code Segment**| |
| If a code segment involves commands to be copied by developers, display the commands in editable mode, instead of using screenshots. Use code snippets to wrap the commands.| |
| Highlight key code segments in blue (RGB: 0.0.255), and comment out key steps.| |
| The code display meets the code indentation requirements.| |
| If an API call is involved in a step, provide the API and its usage description or sample code. The code comes from specific instances.| |
*Describe the software and hardware configurations required by the development environment so that developers can prepare the environment in advance. You can use subtitles if there is a large amount of content.*
***[Example]***
1. Use **AudioStreamInfo.Builder** to create an **AudioStreamInfo** instance for audio stream parameters. The following example uses the default values of the input parameters for **AudioStreamInfo.Builder**. You need to set the parameters based on the audio stream specification.
```
AudioStreamInfo audioStreamInfo = new AudioStreamInfo.Builder()
The following table describes the environment configuration requirements specific to the Hi3861 development board.
**Table 1** Hi3861 development environment-specific requirements
| Platform Type| Development Tool| Function| How to Obtain|
| -------- | -------- | -------- | -------- |
| Linux server| SCons3.0.4+ | Executes script compilation.| Internet|
| Linux server| build-essential | Provides a basic software package for compilation and building.| Internet|
### Setting Up the Environment
***[Writing Requirements]***
*Describe the procedure for setting up the development environment. If there is a large amount of content, use subtitles, for example, "Setting Up the Basic Build Environment" and "Setting Up the Compilation Tool Environment".*
***[Example]***
1. Start a Linux server.
2. Run the following command to install the tool installation package:
Example code for playing a PCM stream:
```
AudioStreamInfo audioStreamInfo = new AudioStreamInfo.Builder().sampleRate(44100)// 44.1 kHz
.audioStreamFlag(AudioStreamInfo.AudioStreamFlag.AUDIO_STREAM_FLAG_MAY_DUCK)// Set audio ducking.
.channelMask(AudioStreamInfo.ChannelMask.CHANNEL_OUT_STEREO)// Set the dual output channel.
.streamUsage(AudioStreamInfo.StreamUsage.STREAM_USAGE_MEDIA)// Set the stream to be used for media.
.build();
```
2. Build the playback parameter structure via **AudioRendererInfo** for the audio stream created in Step 1, and use **AudioRendererInfo.Builder** to create an instance. The following example uses the default parameter values of the **AudioRendererInfo.Builder** instance. You need to set the playback parameters based on the audio playback specification.
```
AudioRendererInfo audioRendererInfo = new AudioRendererInfo.Builder()
3. Run the following command to check whether the tool is successfully installed.
```
AudioRendererInfo audioRendererInfo = new AudioRendererInfo.Builder()
.audioStreamInfo(audioStreamInfo)
.audioStreamOutputFlag(AudioRendererInfo.AudioStreamOutputFlag.AUDIO_STREAM_OUTPUT_FLAG_DIRECT_PCM)// Set direct PCM output.
.bufferSizeInBytes(100)
.distributedDeviceId("E54***5E8")// Use distributed device E54***5E8 for playback.
.isOffload(false)// Value false indicates that the audio stream is transmitted to the buffer on a segment-by-segment basis for several times and then played. Value true indicates that the audio stream is transmitted to the HAL layer at a time.
.build();
xxxxx
```
3. Specify the playback mode based on the audio stream to be played. The playback modes differ only in the data writing process. Create an **AudioRenderer** instance using a constructor that fits your need.
4. After the playback task is complete, call the **release()** method on the **AudioRenderer** instance to release resources.
### Verifying the Environment
***[Writing Requirements]***
*Optional. Provide the criteria for checking whether the environment is set up successfully. You can also provide the criteria along with the environment setup procedure, as provided in the preceding example.*
## *Example Task Scenario* Development (Use a specific scenario name. If there is only one scenario, use the solution/feature/function/module name.)
*Mandatory.*
***[Developers' Concerns]***
*How do I use or access the solution/feature/function/module?*
***[Key Writing Points]***
## (Optional) Commissioning and Verification
*Provide scenarios that are close to actual development scenarios.*
-*Task scenarios are what developers need to use to achieve development objectives.*
-*There can be one or more task scenarios. You can use multiple "Development Guidelines" sections. Follow the hierarchical logic when writing the guidelines, that is, a task scenario -> a subtask scenario -> task logic ("Development Process") -> operation procedure ("How to Develop").*
### *Example Task Scenario* Overview
*Based on the scenario division of the solution/feature/function/module, you can provide either "Example Task Scenario Overview" or "Example Overview", or both of them.*
*1. "Example Overview" provides an overview that is common to all task scenarios of this solution/feature/function/module and that developers need to understand. If there is nothing in common, delete it.*
*2. "Example Task Scenario Overview" describes the contents directly related to a task scenario. The knowledge points and key writing points are the same as those in "Example Overview". In this section, you need to introduce this specific task scenario and describe basic concepts, working principles, constraints, and samples that are directly related to the task scenario. If there is no specific task scenario, delete it.*
### Development Process
***[Key Writing Points]***
-*Optional. If there are many development steps (five or more core operations) or complex logical relationships between steps, provide the development process so that developers can have a panoramic view of the operations to be performed.*
-*Provide flowcharts and tables if necessary.*
### Available APIs
***[Writing Requirements]***
*Optional. After the development is complete, perform commissioning and verification to ensure that the operation is successful. The operation procedure requirements are the same as those in **Development Guidelines**. Other specific writing requirements are as follows. After finishing the writing, check your content against these requirements one by one.*
-*Optional. Describe the key APIs in the development steps and provide the API introduction, so that developers can have a general understanding of development.*
-*If there are more than 10 APIs, provide the main APIs only.*
-*Ensure that the APIs and their functions of the corresponding version are supported when the document is released.*
***[Example]***
Certain APIs can be called only by system applications that have been granted the **SystemCapability.Notification.Notification** permission. The APIs use either a callback or promise to return the result. The tables below list the APIs that use a callback, which provide the same functions as their counterparts that use a promise. For details about the APIs, see the [API document](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-notification.md).
| Describe the final service commissioning process. The operation result of each step should be verified after the corresponding development task is complete.| |
| Specify the criteria for development success.| |
## Development Example
### How to Develop
***[Writing Requirements]***
*Provide a complete sample, briefly describe the principle and implementation of the sample, and provide a link to the source code repository.*
*Mandatory.*
-*Completeness and Correctness*
-*Describe the complete development process (for example, steps related to the code, resources, third-party libraries, and application configuration files in the HAP) so that developers can correctly complete the development. Do not omit key configuration operations.*
-*Ensure that the code snippet provided in the document can be built with the context in DevEco Studio.*
-*Ensure that the complete sample code provided in the document can be run in DevEco Studio, and the execution result is the same as that described in the document.*
-*Clarity*
-*Provide a clear execution owner (who), operation purpose (why), operation content (what/how), and scenario (when/where) for each step. Use imperative sentence to describe steps.*
-*Clearly provide the APIs (if involved) in steps, as well as their usage description and sample code.*
-*Provide development suggestions or precautions for key steps and sample code (comments for sample code).*
*Think about what questions may be raised when developers are performing the operations.**These problems are obstacles to developers.**Provide support information in the document to help them handle these obstacles.**Examples of support information:*
-*Branch selection principle. Provide principles or suggestions for selecting branches and parameters.*
-*Necessary supplementary description. Describe possible special operations, required operation permissions, high efficiency skills, and concise and clear background knowledge.*
-*Precautions. Describe operations that may adversely affect other functions or system performance and reliability, and operations that may cause data loss or security problems.**Provide this type of information in a style different from that of the body prior to the operation procedure.*
-*Error prevention/correction information. Provide guidance for preventing, locating, or rectifying typical problems that may occur in the development process.**This type of information can be provided in "How to Develop" or "FAQs", depending on the content amount.*
-*Standardization*
-*Provide both logically and syntactically correct sample code and write it in a standard manner. Anonymize sensitive information, such as mobile numbers, ID cards, and account names, for example, 186\*\*\*\*\*\*\*\*. Use private IP addresses or a corresponding format, for example, xx.xx.xx.xx and www.example.com, rather than real IP addresses and domain names.*
-*Provide code that complies with the code indentation requirements. Do not use the **Tab** key to indent code. Instead, use four spaces, to avoid incorrect display.*
// Called when the widget host converts the temporary widget into a normal one. The widget provider should do something to respond to the conversion.
console.log('FormAbility onCastToNormal');
},
}
```
### Verification
***[Writing Requirements]***
-*Optional. After the development is complete, provide a guide to check whether the operation is successful if there is an independent commissioning and verification operation. The operation procedure is the same as that described in "How to Develop."*
-*Provide only the final service commissioning. You are advised to verify the operation result of each subtask after the development is complete.*
## FAQs
*Optional.*
***[Developers' Concerns]***
*What are the typical problems that may occur in the development process of the solution/feature/function/module? How do I locate and solve these problems?*
***[Key Writing Points]***
*Describe the problems that may occur during the development and the solutions to them.*
-*Delete this section if there are no common problems.*
-*It is recommended that common problems in each task scenario be described in a separate chapter. Common problems related to a single task scenario be described in the corresponding chapter.*
### 1. XX problem (simple problem)
XXX
### 2. XX problem (complex problem)
**Symptom**
XXX
**Possible Causes**
The following sample is provided to help you better understand how to xx:
