1# Development Guidelines on Audio Playback<a name="EN-US_TOPIC_0000001100255784"></a> 2 3- [When to Use](#section910413166166) 4- [Available APIs](#section1225204317126) 5 6## When to Use<a name="section910413166166"></a> 7 8You use audio playback APIs to convert audio data into audible analog signals, play the audio signals using output devices, and manage playback tasks. 9 10**Figure 1** Playback status<a name="fig19537218164010"></a> 11 12 13## Available APIs<a name="section1225204317126"></a> 14 15**Table 1** media 16 17<a name="table17619171017258"></a> 18<table><thead align="left"><tr id="row9619111017256"><th class="cellrowborder" valign="top" width="42.29%" id="mcps1.2.3.1.1"><p id="p19739153111253"><a name="p19739153111253"></a><a name="p19739153111253"></a>API</p> 19</th> 20<th class="cellrowborder" valign="top" width="57.709999999999994%" id="mcps1.2.3.1.2"><p id="p761918101259"><a name="p761918101259"></a><a name="p761918101259"></a>Description</p> 21</th> 22</tr> 23</thead> 24<tbody><tr id="row186191310102518"><td class="cellrowborder" valign="top" width="42.29%" headers="mcps1.2.3.1.1 "><p id="p152227722614"><a name="p152227722614"></a><a name="p152227722614"></a>media.createAudioPlayer()</p> 25</td> 26<td class="cellrowborder" valign="top" width="57.709999999999994%" headers="mcps1.2.3.1.2 "><p id="p11619510202511"><a name="p11619510202511"></a><a name="p11619510202511"></a>Creates an <strong id="b1189187131414"><a name="b1189187131414"></a><a name="b1189187131414"></a>AudioPlayer</strong> instance.</p> 27</td> 28</tr> 29<tr id="row78247183285"><td class="cellrowborder" valign="top" width="42.29%" headers="mcps1.2.3.1.1 "><p id="p78241186287"><a name="p78241186287"></a><a name="p78241186287"></a><a href="#table3407174718274">AudioPlayer</a></p> 30</td> 31<td class="cellrowborder" valign="top" width="57.709999999999994%" headers="mcps1.2.3.1.2 "><p id="p1382410184281"><a name="p1382410184281"></a><a name="p1382410184281"></a>Provides audio playback methods.</p> 32</td> 33</tr> 34</tbody> 35</table> 36 37**Table 2** AudioPlayer 38 39<a name="table3407174718274"></a> 40<table><thead align="left"><tr id="row640744712719"><th class="cellrowborder" valign="top" width="42.980000000000004%" id="mcps1.2.3.1.1"><p id="p1540794717271"><a name="p1540794717271"></a><a name="p1540794717271"></a>API</p> 41</th> 42<th class="cellrowborder" valign="top" width="57.02%" id="mcps1.2.3.1.2"><p id="p14407204712274"><a name="p14407204712274"></a><a name="p14407204712274"></a>Description</p> 43</th> 44</tr> 45</thead> 46<tbody><tr id="row540714712272"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p174086470278"><a name="p174086470278"></a><a name="p174086470278"></a>release()</p> 47</td> 48<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p204082047172719"><a name="p204082047172719"></a><a name="p204082047172719"></a>Releases audio resources.</p> 49</td> 50</tr> 51<tr id="row12408104792716"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p640874762718"><a name="p640874762718"></a><a name="p640874762718"></a>play()</p> 52</td> 53<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p1740894712718"><a name="p1740894712718"></a><a name="p1740894712718"></a>Starts audio playback.</p> 54</td> 55</tr> 56<tr id="row84081747182715"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p04081947172716"><a name="p04081947172716"></a><a name="p04081947172716"></a>pause()</p> 57</td> 58<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p164081547132711"><a name="p164081547132711"></a><a name="p164081547132711"></a>Pauses playback.</p> 59</td> 60</tr> 61<tr id="row184082047132717"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p74086479279"><a name="p74086479279"></a><a name="p74086479279"></a>stop()</p> 62</td> 63<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p1140814471274"><a name="p1140814471274"></a><a name="p1140814471274"></a>Stops playback.</p> 64</td> 65</tr> 66<tr id="row93063645415"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p230715618541"><a name="p230715618541"></a><a name="p230715618541"></a>reset()<sup id="sup15868135520538"><a name="sup15868135520538"></a><a name="sup15868135520538"></a>7+</sup></p> 67</td> 68<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p530714615545"><a name="p530714615545"></a><a name="p530714615545"></a>Resets the audio source to be played.</p> 69</td> 70</tr> 71<tr id="row36221450105715"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p162210506572"><a name="p162210506572"></a><a name="p162210506572"></a>setVolume(vol: number)</p> 72</td> 73<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p166221550165720"><a name="p166221550165720"></a><a name="p166221550165720"></a>Sets playback volume.</p> 74</td> 75</tr> 76<tr id="row1240804752711"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p8408647172716"><a name="p8408647172716"></a><a name="p8408647172716"></a>seek(timeMs: number)</p> 77</td> 78<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p440817478271"><a name="p440817478271"></a><a name="p440817478271"></a>Changes the playback position.</p> 79</td> 80</tr> 81<tr id="row5408194714279"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p144081547102712"><a name="p144081547102712"></a><a name="p144081547102712"></a>src:string</p> 82</td> 83<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p1040814782716"><a name="p1040814782716"></a><a name="p1040814782716"></a>Defines the URI of an audio file to play.</p> 84</td> 85</tr> 86<tr id="row155026127182"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p633012347"><a name="p633012347"></a><a name="p633012347"></a>state:AudioState</p> 87</td> 88<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p105031612141811"><a name="p105031612141811"></a><a name="p105031612141811"></a>Defines a playback state.</p> 89</td> 90</tr> 91<tr id="row340854714273"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p16234263330"><a name="p16234263330"></a><a name="p16234263330"></a>currentTime:number</p> 92</td> 93<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p3409174762710"><a name="p3409174762710"></a><a name="p3409174762710"></a>Defines the current playback position.</p> 94</td> 95</tr> 96<tr id="row6409134710274"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p114091047162711"><a name="p114091047162711"></a><a name="p114091047162711"></a>duration:number</p> 97</td> 98<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p154091247132715"><a name="p154091247132715"></a><a name="p154091247132715"></a>Defines the playback duration.</p> 99</td> 100</tr> 101<tr id="row4409134772717"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p9681449141811"><a name="p9681449141811"></a><a name="p9681449141811"></a>loop:boolean</p> 102</td> 103<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p94091847102711"><a name="p94091847102711"></a><a name="p94091847102711"></a>Defines whether to loop audio playback.</p> 104</td> 105</tr> 106<tr id="row44091647192718"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p18937155862412"><a name="p18937155862412"></a><a name="p18937155862412"></a>on('play', function callback)</p> 107</td> 108<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p13409164722717"><a name="p13409164722717"></a><a name="p13409164722717"></a>Listens for the playback start event.</p> 109</td> 110</tr> 111<tr id="row12409154711272"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p124091474279"><a name="p124091474279"></a><a name="p124091474279"></a>on('pause', function callback)</p> 112</td> 113<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p7409174714274"><a name="p7409174714274"></a><a name="p7409174714274"></a>Listens for the playback pause event.</p> 114</td> 115</tr> 116<tr id="row040917477273"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p18981171411254"><a name="p18981171411254"></a><a name="p18981171411254"></a>on('stop', function callback)</p> 117</td> 118<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p1409164772714"><a name="p1409164772714"></a><a name="p1409164772714"></a>Listens for the playback stop event.</p> 119</td> 120</tr> 121<tr id="row712184163016"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p1167517115311"><a name="p1167517115311"></a><a name="p1167517115311"></a>on('reset', function callback)</p> 122</td> 123<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p1113134115301"><a name="p1113134115301"></a><a name="p1113134115301"></a>Listens for the playback reset event.</p> 124</td> 125</tr> 126<tr id="row11409747202711"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p189901420102514"><a name="p189901420102514"></a><a name="p189901420102514"></a>on('finish',function callback)</p> 127</td> 128<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p8410124742713"><a name="p8410124742713"></a><a name="p8410124742713"></a>Listens for the playback end event.</p> 129</td> 130</tr> 131<tr id="row64105474278"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p166588276253"><a name="p166588276253"></a><a name="p166588276253"></a>on('error', function callback)</p> 132</td> 133<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p54101047102712"><a name="p54101047102712"></a><a name="p54101047102712"></a>Listens for the playback error event.</p> 134</td> 135</tr> 136<tr id="row1410154715273"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p135217361257"><a name="p135217361257"></a><a name="p135217361257"></a>on('dataload', function callback)</p> 137</td> 138<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p1541054719271"><a name="p1541054719271"></a><a name="p1541054719271"></a>Listens for the data loading event.</p> 139</td> 140</tr> 141<tr id="row126521548145814"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p2652134812586"><a name="p2652134812586"></a><a name="p2652134812586"></a>on('volumeChange', function callback)</p> 142</td> 143<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p116527483584"><a name="p116527483584"></a><a name="p116527483584"></a>Listens for the volume change event.</p> 144</td> 145</tr> 146<tr id="row1410124732711"><td class="cellrowborder" valign="top" width="42.980000000000004%" headers="mcps1.2.3.1.1 "><p id="p942310426254"><a name="p942310426254"></a><a name="p942310426254"></a>on('timeUpdate', function callback)</p> 147</td> 148<td class="cellrowborder" valign="top" width="57.02%" headers="mcps1.2.3.1.2 "><p id="p18410144715271"><a name="p18410144715271"></a><a name="p18410144715271"></a>Listens for the progress change event.</p> 149</td> 150</tr> 151</tbody> 152</table> 153 1541. Create an audio player. 155 156 ``` 157 var player = media.createAudioPlayer(); 158 ``` 159 1602. Set the listeners. 161 162 ``` 163 player.on('play', (err, action) => { 164 if (err) { 165 console.error('Error returned in the play() callback.'); 166 return; 167 } 168 console.info('Current player duration: '+ player.duration); 169 console.info('Current player time: ' + player.currentTime); 170 console.info('Current player status: '+player.state); 171 console.info('Pause MP3'); 172 player.pause(); 173 }); 174 player.on('pause', (err, action) => { 175 if (err) { 176 console.error('Error returned in the pause() callback.'); 177 return; 178 } 179 console.info('Current player status: ' + player.state); 180 console.info('Current player time: ' + player.currentTime); 181 player.seek(30000); // Seek for 30 seconds. 182 }); 183 player.on('stop', (err, action) => { 184 if (err) { 185 console.error('Error returned in the stop() callback.'); 186 return; 187 } 188 console.info('stop callback invoked. State:' + player.state); 189 player.reset(); 190 }); 191 player.on('dataLoad', (err, action) => { 192 if (err) { 193 console.error('Error returned in the dataLoad() callback.'); 194 return; 195 } 196 console.info('dataLoad callback invoked. Current time: ' + player.currentTime); 197 console.info('Duration of the source:' + player.duration); 198 player.play(); 199 }); 200 player.on('reset', (err, action) => { 201 if (err) { 202 console.error('Error returned in the reset() callback.'); 203 return; 204 } 205 console.info('reset callback invoked.'); 206 player.release(); 207 }); 208 player.on('finish', (err, action) => { 209 if (err) { 210 console.error('Error returned in the finish() callback.'); 211 return; 212 } 213 console.info('finish callback invoked.'); 214 }); 215 player.on('timeUpdate', (seekTime, action) => { 216 console.info('Seek time: ' + seekTime); 217 console.info('Current player time: ' + player.currentTime); 218 var newTime = player.currentTime; 219 if(newTime == 30000) { 220 console.info('Seek succeeded. New time: ' + newTime); 221 } else { 222 console.error('Seek failed: ', + newTime); 223 } 224 player.stop(); 225 }); 226 player.on('error', (err) => { 227 console.error('Player error: ${err.message}'); 228 }); 229 ``` 230 2313. Start playback. 232 233 ``` 234 var audioSourceMp3 = 'file://test.mp3'; 235 player.src = audioSourceMp3; 236 player.loop = true; 237 ``` 238 239 240
