audio.go 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429
  1. // Copyright 2015 Hajime Hoshi
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. // Package audio provides audio players.
  15. //
  16. // The stream format must be 16-bit little endian and 2 channels. The format is as follows:
  17. // [data] = [sample 1] [sample 2] [sample 3] ...
  18. // [sample *] = [channel 1] ...
  19. // [channel *] = [byte 1] [byte 2] ...
  20. //
  21. // An audio context (audio.Context object) has a sample rate you can specify and all streams you want to play must have the same
  22. // sample rate. However, decoders in e.g. audio/mp3 package adjust sample rate automatically,
  23. // and you don't have to care about it as long as you use those decoders.
  24. //
  25. // An audio context can generate 'players' (audio.Player objects),
  26. // and you can play sound by calling Play function of players.
  27. // When multiple players play, mixing is automatically done.
  28. // Note that too many players may cause distortion.
  29. //
  30. // For the simplest example to play sound, see wav package in the examples.
  31. package audio
  32. import (
  33. "bytes"
  34. "errors"
  35. "fmt"
  36. "io"
  37. "runtime"
  38. "sync"
  39. "time"
  40. "github.com/hajimehoshi/ebiten/v2/internal/hooks"
  41. )
  42. const (
  43. channelNum = 2
  44. bitDepthInBytes = 2
  45. bytesPerSample = bitDepthInBytes * channelNum
  46. )
  47. // A Context represents a current state of audio.
  48. //
  49. // At most one Context object can exist in one process.
  50. // This means only one constant sample rate is valid in your one application.
  51. //
  52. // For a typical usage example, see examples/wav/main.go.
  53. type Context struct {
  54. playerFactory *playerFactory
  55. // inited represents whether the audio device is initialized and available or not.
  56. // On Android, audio loop cannot be started unless JVM is accessible. After updating one frame, JVM should exist.
  57. inited chan struct{}
  58. initedOnce sync.Once
  59. sampleRate int
  60. err error
  61. ready bool
  62. readyOnce sync.Once
  63. players map[*player]struct{}
  64. m sync.Mutex
  65. semaphore chan struct{}
  66. }
  67. var (
  68. theContext *Context
  69. theContextLock sync.Mutex
  70. )
  71. // NewContext creates a new audio context with the given sample rate.
  72. //
  73. // The sample rate is also used for decoding MP3 with audio/mp3 package
  74. // or other formats as the target sample rate.
  75. //
  76. // sampleRate should be 44100 or 48000.
  77. // Other values might not work.
  78. // For example, 22050 causes error on Safari when decoding MP3.
  79. //
  80. // NewContext panics when an audio context is already created.
  81. func NewContext(sampleRate int) *Context {
  82. theContextLock.Lock()
  83. defer theContextLock.Unlock()
  84. if theContext != nil {
  85. panic("audio: context is already created")
  86. }
  87. c := &Context{
  88. sampleRate: sampleRate,
  89. playerFactory: newPlayerFactory(sampleRate),
  90. players: map[*player]struct{}{},
  91. inited: make(chan struct{}),
  92. semaphore: make(chan struct{}, 1),
  93. }
  94. theContext = c
  95. h := getHook()
  96. h.OnSuspendAudio(func() error {
  97. c.semaphore <- struct{}{}
  98. c.playerFactory.suspend()
  99. return nil
  100. })
  101. h.OnResumeAudio(func() error {
  102. <-c.semaphore
  103. c.playerFactory.resume()
  104. return nil
  105. })
  106. h.AppendHookOnBeforeUpdate(func() error {
  107. c.initedOnce.Do(func() {
  108. close(c.inited)
  109. })
  110. var err error
  111. theContextLock.Lock()
  112. if theContext != nil {
  113. theContext.m.Lock()
  114. err = theContext.err
  115. theContext.m.Unlock()
  116. }
  117. theContextLock.Unlock()
  118. if err != nil {
  119. return err
  120. }
  121. if err := c.gcPlayers(); err != nil {
  122. return err
  123. }
  124. return nil
  125. })
  126. return c
  127. }
  128. // CurrentContext returns the current context or nil if there is no context.
  129. func CurrentContext() *Context {
  130. theContextLock.Lock()
  131. c := theContext
  132. theContextLock.Unlock()
  133. return c
  134. }
  135. func (c *Context) hasError() bool {
  136. c.m.Lock()
  137. r := c.err != nil
  138. c.m.Unlock()
  139. return r
  140. }
  141. func (c *Context) setError(err error) {
  142. // TODO: What if c.err already exists?
  143. c.m.Lock()
  144. c.err = err
  145. c.m.Unlock()
  146. }
  147. func (c *Context) setReady() {
  148. c.m.Lock()
  149. c.ready = true
  150. c.m.Unlock()
  151. }
  152. func (c *Context) addPlayer(p *player) {
  153. c.m.Lock()
  154. defer c.m.Unlock()
  155. c.players[p] = struct{}{}
  156. // Check the source duplication
  157. srcs := map[io.Reader]struct{}{}
  158. for p := range c.players {
  159. if _, ok := srcs[p.source()]; ok {
  160. c.err = errors.New("audio: a same source is used by multiple Player")
  161. return
  162. }
  163. srcs[p.source()] = struct{}{}
  164. }
  165. }
  166. func (c *Context) removePlayer(p *player) {
  167. c.m.Lock()
  168. delete(c.players, p)
  169. c.m.Unlock()
  170. }
  171. func (c *Context) gcPlayers() error {
  172. c.m.Lock()
  173. defer c.m.Unlock()
  174. // Now reader players cannot call removePlayers from themselves in the current implementation.
  175. // Underlying playering can be the pause state after fishing its playing,
  176. // but there is no way to notify this to players so far.
  177. // Instead, let's check the states proactively every frame.
  178. for p := range c.players {
  179. if err := p.Err(); err != nil {
  180. return err
  181. }
  182. if !p.IsPlaying() {
  183. delete(c.players, p)
  184. }
  185. }
  186. return nil
  187. }
  188. // IsReady returns a boolean value indicating whether the audio is ready or not.
  189. //
  190. // On some browsers, user interaction like click or pressing keys is required to start audio.
  191. func (c *Context) IsReady() bool {
  192. c.m.Lock()
  193. defer c.m.Unlock()
  194. r := c.ready
  195. if r {
  196. return r
  197. }
  198. if len(c.players) != 0 {
  199. return r
  200. }
  201. c.readyOnce.Do(func() {
  202. // Create another goroutine since (*Player).Play can lock the context's mutex.
  203. // TODO: Is this needed for reader players?
  204. go func() {
  205. // The audio context is never ready unless there is a player. This is
  206. // problematic when a user tries to play audio after the context is ready.
  207. // Play a dummy player to avoid the blocking (#969).
  208. // Use a long enough buffer so that writing doesn't finish immediately (#970).
  209. p := NewPlayerFromBytes(c, make([]byte, bufferSize()*2))
  210. p.Play()
  211. }()
  212. })
  213. return r
  214. }
  215. // SampleRate returns the sample rate.
  216. func (c *Context) SampleRate() int {
  217. return c.sampleRate
  218. }
  219. func (c *Context) acquireSemaphore() {
  220. c.semaphore <- struct{}{}
  221. }
  222. func (c *Context) releaseSemaphore() {
  223. <-c.semaphore
  224. }
  225. func (c *Context) waitUntilInited() {
  226. <-c.inited
  227. }
  228. // Player is an audio player which has one stream.
  229. //
  230. // Even when all references to a Player object is gone,
  231. // the object is not GCed until the player finishes playing.
  232. // This means that if a Player plays an infinite stream,
  233. // the object is never GCed unless Close is called.
  234. type Player struct {
  235. p *player
  236. }
  237. // NewPlayer creates a new player with the given stream.
  238. //
  239. // src's format must be linear PCM (16bits little endian, 2 channel stereo)
  240. // without a header (e.g. RIFF header).
  241. // The sample rate must be same as that of the audio context.
  242. //
  243. // The player is seekable when src is io.Seeker.
  244. // Attempt to seek the player that is not io.Seeker causes panic.
  245. //
  246. // Note that the given src can't be shared with other Player objects.
  247. //
  248. // NewPlayer tries to call Seek of src to get the current position.
  249. // NewPlayer returns error when the Seek returns error.
  250. //
  251. // A Player doesn't close src even if src implements io.Closer.
  252. // Closing the source is src owner's responsibility.
  253. func (c *Context) NewPlayer(src io.Reader) (*Player, error) {
  254. pi, err := c.playerFactory.newPlayer(c, src)
  255. if err != nil {
  256. return nil, err
  257. }
  258. p := &Player{pi}
  259. runtime.SetFinalizer(p, (*Player).finalize)
  260. return p, nil
  261. }
  262. // NewPlayer creates a new player with the given stream.
  263. //
  264. // Deprecated: as of v2.2. Use (*Context).NewPlayer instead.
  265. func NewPlayer(context *Context, src io.Reader) (*Player, error) {
  266. return context.NewPlayer(src)
  267. }
  268. // NewPlayerFromBytes creates a new player with the given bytes.
  269. //
  270. // As opposed to NewPlayer, you don't have to care if src is already used by another player or not.
  271. // src can be shared by multiple players.
  272. //
  273. // The format of src should be same as noted at NewPlayer.
  274. func (c *Context) NewPlayerFromBytes(src []byte) *Player {
  275. p, err := c.NewPlayer(bytes.NewReader(src))
  276. if err != nil {
  277. // Errors should never happen.
  278. panic(fmt.Sprintf("audio: %v at NewPlayerFromBytes", err))
  279. }
  280. return p
  281. }
  282. // NewPlayerFromBytes creates a new player with the given bytes.
  283. //
  284. // Deprecated: as of v2.2. Use (*Context).NewPlayerFromBytes instead.
  285. func NewPlayerFromBytes(context *Context, src []byte) *Player {
  286. return context.NewPlayerFromBytes(src)
  287. }
  288. func (p *Player) finalize() {
  289. runtime.SetFinalizer(p, nil)
  290. if !p.IsPlaying() {
  291. p.Close()
  292. }
  293. }
  294. // Close closes the stream.
  295. //
  296. // When Close is called, the stream owned by the player is NOT closed,
  297. // even if the stream implements io.Closer.
  298. //
  299. // Close returns error when the player is already closed.
  300. func (p *Player) Close() error {
  301. return p.p.Close()
  302. }
  303. // Play plays the stream.
  304. func (p *Player) Play() {
  305. p.p.Play()
  306. }
  307. // IsPlaying returns boolean indicating whether the player is playing.
  308. func (p *Player) IsPlaying() bool {
  309. return p.p.IsPlaying()
  310. }
  311. // Rewind rewinds the current position to the start.
  312. //
  313. // The passed source to NewPlayer must be io.Seeker, or Rewind panics.
  314. //
  315. // Rewind returns error when seeking the source stream returns error.
  316. func (p *Player) Rewind() error {
  317. return p.p.Rewind()
  318. }
  319. // Seek seeks the position with the given offset.
  320. //
  321. // The passed source to NewPlayer must be io.Seeker, or Seek panics.
  322. //
  323. // Seek returns error when seeking the source stream returns error.
  324. func (p *Player) Seek(offset time.Duration) error {
  325. return p.p.Seek(offset)
  326. }
  327. // Pause pauses the playing.
  328. func (p *Player) Pause() {
  329. p.p.Pause()
  330. }
  331. // Current returns the current position in time.
  332. //
  333. // As long as the player continues to play, Current's returning value is increased monotonically,
  334. // even though the source stream loops and its position goes back.
  335. func (p *Player) Current() time.Duration {
  336. return p.p.Current()
  337. }
  338. // Volume returns the current volume of this player [0-1].
  339. func (p *Player) Volume() float64 {
  340. return p.p.Volume()
  341. }
  342. // SetVolume sets the volume of this player.
  343. // volume must be in between 0 and 1. SetVolume panics otherwise.
  344. func (p *Player) SetVolume(volume float64) {
  345. p.p.SetVolume(volume)
  346. }
  347. type hook interface {
  348. OnSuspendAudio(f func() error)
  349. OnResumeAudio(f func() error)
  350. AppendHookOnBeforeUpdate(f func() error)
  351. }
  352. var hookForTesting hook
  353. func getHook() hook {
  354. if hookForTesting != nil {
  355. return hookForTesting
  356. }
  357. return &hookImpl{}
  358. }
  359. type hookImpl struct{}
  360. func (h *hookImpl) OnSuspendAudio(f func() error) {
  361. hooks.OnSuspendAudio(f)
  362. }
  363. func (h *hookImpl) OnResumeAudio(f func() error) {
  364. hooks.OnResumeAudio(f)
  365. }
  366. func (h *hookImpl) AppendHookOnBeforeUpdate(f func() error) {
  367. hooks.AppendHookOnBeforeUpdate(f)
  368. }