From 4336aa1ab1a1893200462d1e06942cf1bf4f8bad Mon Sep 17 00:00:00 2001
From: streamich <streamich@gmail.com>
Date: Sun, 28 Oct 2018 10:25:31 +0100
Subject: [PATCH 1/3] =?UTF-8?q?feat:=20=F0=9F=8E=B8=20add=20useAudio=20hoo?=
 =?UTF-8?q?k?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                          |   4 +
 docs/useAudio.md                   |  86 ++++++++++++++
 src/__stories__/useAudio.story.tsx |  36 ++++++
 src/index.ts                       |   2 +
 src/react.ts                       |   3 +-
 src/useAudio.ts                    | 177 +++++++++++++++++++++++++++++
 src/useSetState.ts                 |   8 +-
 src/util/parseTimeRanges.ts        |  14 +++
 8 files changed, 325 insertions(+), 5 deletions(-)
 create mode 100644 docs/useAudio.md
 create mode 100644 src/__stories__/useAudio.story.tsx
 create mode 100644 src/useAudio.ts
 create mode 100644 src/util/parseTimeRanges.ts

diff --git a/README.md b/README.md
index acb79433..5519780b 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,10 @@
    - [`useWindowSize`](./docs/useWindowSize.md) &mdash; tracks `Window` dimensions.
      <br/>
      <br/>
+- [__UI__](./docs/UI.md)
+   - [`useAudio`](./docs/useAudio.md) &mdash; plays audio and exposes controls.
+     <br/>
+     <br/>
 - [__Animations__](./docs/Animations.md)
    - [`useRaf`](./docs/useRaf.md) &mdash; re-renders component on each `reaquestAnimationFrame`.
    - [`useSpring`](./docs/useSpring.md) &mdash; interpolates number over time according to spring dynamics.
diff --git a/docs/useAudio.md b/docs/useAudio.md
new file mode 100644
index 00000000..b654ae93
--- /dev/null
+++ b/docs/useAudio.md
@@ -0,0 +1,86 @@
+# `useAudio`
+
+Creates `<audio>` element, tracks its state and exposes playback conrols.
+
+
+## Usage
+
+```jsx
+import {useAudio} from 'react-use';
+
+const src = 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-2.mp3';
+
+const Demo = () => {
+  const [audio, state, controls, ref] = useAudio({
+    src,
+    autoPlay: true,
+  });
+
+  return (
+    <div>
+      {audio}
+      <pre>{JSON.stringify(state, null, 2)}</pre>
+      <button onClick={controls.pause}>Pause</button>
+      <button onClick={controls.play}>Play</button>
+      <br/>
+      <button onClick={controls.mute}>Mute</button>
+      <button onClick={controls.unmute}>Un-mute</button>
+      <br/>
+      <button onClick={() => controls.volume(.1)}>Volume: 10%</button>
+      <button onClick={() => controls.volume(.5)}>Volume: 50%</button>
+      <button onClick={() => controls.volume(1)}>Volume: 100%</button>
+      <br/>
+      <button onClick={() => controls.seek(state.time - 5)}>-5 sec</button>
+      <button onClick={() => controls.seek(state.time + 5)}>+5 sec</button>
+    </div>
+  );
+};
+```
+
+
+## Reference
+
+```ts
+const [audio, state, controls, ref] = useAudio(props);
+```
+
+`audio` is React's `<audio>` element that you have to insert somewhere in your
+render tree, for example
+
+```jsx
+<div>{audio}</div>
+```
+
+`state` represents the state of the audio and the the following shape
+
+```json
+{
+  "buffered": [
+    {
+      "start": 0,
+      "end": 425.952625
+    }
+  ],
+  "time": 5.244996,
+  "duration": 425.952625,
+  "isPlaying": false,
+  "muted": false,
+  "volume": 1
+}
+```
+
+`controls` is a list collection of methods that allow you to control the
+playback of the audio, it has the following interface
+
+```ts
+interface AudioControls {
+  play: () => Promise<void> | void;
+  pause: () => void;
+  mute: () => void;
+  unmute: () => void;
+  volume: (volume: number) => void;
+  seek: (time: number) => void;
+}
+```
+
+And finally, `props` &mdash; all props that `<audio>` accepts.
diff --git a/src/__stories__/useAudio.story.tsx b/src/__stories__/useAudio.story.tsx
new file mode 100644
index 00000000..c6aa1160
--- /dev/null
+++ b/src/__stories__/useAudio.story.tsx
@@ -0,0 +1,36 @@
+import * as React from 'react';
+import {storiesOf} from '@storybook/react';
+import {useAudio} from '..';
+
+const src = 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-2.mp3';
+
+const Demo = () => {
+  const [audio, state, controls] = useAudio({
+    src,
+    autoPlay: true,
+  });
+
+  return (
+    <div>
+      {audio}
+      <pre>{JSON.stringify(state, null, 2)}</pre>
+      <button onClick={controls.pause}>Pause</button>
+      <button onClick={controls.play}>Play</button>
+      <br/>
+      <button onClick={controls.mute}>Mute</button>
+      <button onClick={controls.unmute}>Un-mute</button>
+      <br/>
+      <button onClick={() => controls.volume(.1)}>Volume: 10%</button>
+      <button onClick={() => controls.volume(.5)}>Volume: 50%</button>
+      <button onClick={() => controls.volume(1)}>Volume: 100%</button>
+      <br/>
+      <button onClick={() => controls.seek(state.time - 5)}>-5 sec</button>
+      <button onClick={() => controls.seek(state.time + 5)}>+5 sec</button>
+    </div>
+  );
+};
+
+storiesOf('useAudio', module)
+  .add('Example', () =>
+    <Demo/>
+  )
diff --git a/src/index.ts b/src/index.ts
index b56901f3..cd2a00b0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,4 +1,5 @@
 import useAsync from './useAsync';
+import useAudio from './useAudio';
 import useBattery from './useBattery';
 import useCounter from './useCounter';
 import useCss from './useCss';
@@ -31,6 +32,7 @@ import useWindowSize from './useWindowSize';
 
 export {
   useAsync,
+  useAudio,
   useBattery,
   useCounter,
   useCss,
diff --git a/src/react.ts b/src/react.ts
index 977df038..69defde9 100644
--- a/src/react.ts
+++ b/src/react.ts
@@ -6,7 +6,8 @@ export const useState: UseState = (React as any).useState;
 export type UseEffect = (didUpdate: () => ((() => void) | void), params?: any[]) => void;
 export const useEffect: UseEffect = (React as any).useEffect;
 
-export type UseRef = <T>(initialValue: T) => {current: T};
+export interface ReactRef<T> {current: T};
+export type UseRef = <T>(initialValue: T) => ReactRef<T>;
 export const useRef: UseRef = (React as any).useRef;
 
 export type UseCallback = <T extends ((...args: any[]) => any)>(callback: T, args: any[]) => T;
diff --git a/src/useAudio.ts b/src/useAudio.ts
new file mode 100644
index 00000000..50a8e5da
--- /dev/null
+++ b/src/useAudio.ts
@@ -0,0 +1,177 @@
+import * as React from 'react';
+import {useEffect, useRef, ReactRef} from './react';
+import useSetState from './useSetState';
+import parseTimeRanges from './util/parseTimeRanges';
+
+export interface AudioProps extends React.AudioHTMLAttributes<any> {
+  src: string;
+}
+
+export interface AudioState {
+  buffered: any[];
+  duration: number;
+  isPlaying: boolean;
+  muted: boolean;
+  time: number;
+  volume: number;
+}
+
+export interface AudioControls {
+  play: () => Promise<void> | void;
+  pause: () => void;
+  mute: () => void;
+  unmute: () => void;
+  volume: (volume: number) => void;
+  seek: (time: number) => void;
+}
+
+const useAudio = (props: AudioProps): [React.ReactElement<AudioProps>, AudioState, AudioControls, ReactRef<HTMLAudioElement | null>] => {
+  const [state, setState] = useSetState<AudioState>({
+    buffered: [],
+    time: 0,
+    duration: 0,
+    isPlaying: false,
+    muted: false,
+    volume: 1,
+  });
+  const ref = useRef<HTMLAudioElement | null>(null);
+
+  const wrapEvent = (userEvent, proxyEvent?) => {
+    return (event) => {
+      try {
+        proxyEvent && proxyEvent(event);
+      } finally {
+        userEvent && userEvent(event);
+      }
+    };
+  };
+
+  const onPlay = () => setState({isPlaying: true});
+  const onPause = () => setState({isPlaying: false});
+  const onVolumeChange = (event) => {
+    const el = ref.current;
+    if (!el) return;
+    setState({
+      muted: el.muted,
+      volume: el.volume,
+    });
+  };
+  const onDurationChange = (event) => {
+    const el = ref.current;
+    if (!el) return;
+    const {duration, buffered} = el;
+    setState({
+      duration,
+      buffered: parseTimeRanges(buffered),
+    });
+  };
+  const onTimeUpdate = () => {
+    const el = ref.current;
+    if (!el) return;
+    setState({time: el.currentTime});
+  };
+  const onProgress = (event) => {
+    const el = ref.current;
+    if (!el) return;
+    setState({buffered: parseTimeRanges(el.buffered)});
+  };
+
+  const element = React.createElement('audio', {
+    controls: false,
+    ...props,
+    ref,
+    onPlay: wrapEvent(props.onPlay, onPlay),
+    onPause: wrapEvent(props.onPause, onPause),
+    onVolumeChange: wrapEvent(props.onVolumeChange, onVolumeChange),
+    onDurationChange: wrapEvent(props.onDurationChange, onDurationChange),
+    onTimeUpdate: wrapEvent(props.onTimeUpdate, onTimeUpdate),
+    onProgress: wrapEvent(props.onProgress, onProgress),
+  });
+
+  // Some browsers return `Promise` on `.play()` and may throw errors
+  // if one tries to execute another `.play()` or `.pause()` while that
+  // promise is resolving. So we prevent that with this lock.
+  // See: https://bugs.chromium.org/p/chromium/issues/detail?id=593273
+  let lockPlay: boolean = false;
+
+  const controls = {
+    play: () => {
+      const el = ref.current;
+      if (!el) return undefined;
+
+      if (!lockPlay) {
+        const promise = el.play();
+        const isPromise = typeof promise === 'object';
+  
+        if (isPromise) {
+          lockPlay = true;
+          const resetLock = () => {
+            lockPlay = false;
+          };
+          promise.then(resetLock, resetLock);
+        }
+
+        return promise;
+      }
+      return undefined;
+    },
+    pause: () => {
+      const el = ref.current;
+      if (el && !lockPlay) {
+        return el.pause();
+      }
+    },
+    seek: (time: number) => {
+      const el = ref.current;
+      if (!el || (state.duration === undefined)) return;
+      time = Math.min(state.duration, Math.max(0, time));
+      el.currentTime = time;
+    },
+    volume: (volume: number) => {
+      const el = ref.current;
+      if (!el) return;
+      volume = Math.min(1, Math.max(0, volume));
+      el.volume = volume;
+      setState({volume});
+    },
+    mute: () => {
+      const el = ref.current;
+      if (!el) return;
+      el.muted = true;
+    },
+    unmute: () => {
+      const el = ref.current;
+      if (!el) return;
+      el.muted = false;
+    },
+  };
+
+  useEffect(() => {
+    const el = ref.current!;
+
+    if (!el) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.error(
+          'useAudio() ref to <audio> element is empty at mount. ' + 
+          'It seem you have not rendered the audio element, which is ' +
+          'returns as the first argument const [audio] = useAudio(...).'
+        );
+      }
+      return;
+    }
+    
+    // Start media, if autoPlay requested.
+    if (props.autoPlay && el.paused) {
+      controls.play();
+    }
+
+    setState({
+      volume: el.volume,
+      muted: el.muted,
+    });
+  }, [props.src]);
+
+  return [element, state, controls, ref];
+};
+
+export default useAudio;
diff --git a/src/useSetState.ts b/src/useSetState.ts
index db7a0d5b..cc1cbca4 100644
--- a/src/useSetState.ts
+++ b/src/useSetState.ts
@@ -2,10 +2,10 @@ import {useState} from './react';
 
 const useSetState = <T extends object>(initialState: T = {} as T): [T, (patch: Partial<T>) => void]=> {
   const [state, set] = useState<T>(initialState);
-  const setState = (patch) => set({
-    ...(state as object),
-    ...patch,
-  });
+  const setState = (patch) => {
+    Object.assign(state, patch);
+    set(state);
+  };
 
   return [state, setState];
 };
diff --git a/src/util/parseTimeRanges.ts b/src/util/parseTimeRanges.ts
new file mode 100644
index 00000000..83b667d3
--- /dev/null
+++ b/src/util/parseTimeRanges.ts
@@ -0,0 +1,14 @@
+const parseTimeRanges = (ranges) => {
+  const result: ({start: number, end: number})[] = [];
+
+  for (let i = 0; i < ranges.length; i++) {
+    result.push({
+      start: ranges.start(i),
+      end: ranges.end(i)
+    });
+  }
+
+  return result;
+};
+
+export default parseTimeRanges;

From 09526582ceac45db3530e24ca58765cd57e52e20 Mon Sep 17 00:00:00 2001
From: streamich <streamich@gmail.com>
Date: Sun, 28 Oct 2018 10:29:26 +0100
Subject: [PATCH 2/3] =?UTF-8?q?docs:=20=E2=9C=8F=EF=B8=8F=20improve=20useA?=
 =?UTF-8?q?udio=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md        | 2 +-
 docs/useAudio.md | 9 ++++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 5519780b..3d54b8d1 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@
      <br/>
      <br/>
 - [__UI__](./docs/UI.md)
-   - [`useAudio`](./docs/useAudio.md) &mdash; plays audio and exposes controls.
+   - [`useAudio`](./docs/useAudio.md) &mdash; plays audio and exposes its controls.
      <br/>
      <br/>
 - [__Animations__](./docs/Animations.md)
diff --git a/docs/useAudio.md b/docs/useAudio.md
index b654ae93..24fe7475 100644
--- a/docs/useAudio.md
+++ b/docs/useAudio.md
@@ -45,13 +45,13 @@ const [audio, state, controls, ref] = useAudio(props);
 ```
 
 `audio` is React's `<audio>` element that you have to insert somewhere in your
-render tree, for example
+render tree, for example:
 
 ```jsx
 <div>{audio}</div>
 ```
 
-`state` represents the state of the audio and the the following shape
+`state` tracks the state of the audio and has the following shape:
 
 ```json
 {
@@ -70,7 +70,7 @@ render tree, for example
 ```
 
 `controls` is a list collection of methods that allow you to control the
-playback of the audio, it has the following interface
+playback of the audio, it has the following interface:
 
 ```ts
 interface AudioControls {
@@ -83,4 +83,7 @@ interface AudioControls {
 }
 ```
 
+`ref` is a React reference to HTML `<audio>` element, you can access the element by
+`ref.current`, note that it may be `null`.
+
 And finally, `props` &mdash; all props that `<audio>` accepts.

From 2e27efc4c196117d852014e858fccfa1fa47b119 Mon Sep 17 00:00:00 2001
From: streamich <streamich@gmail.com>
Date: Sun, 28 Oct 2018 10:29:51 +0100
Subject: [PATCH 3/3] =?UTF-8?q?chore:=20=F0=9F=A4=96=20release=20v1.6.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index ee714b95..7b97deb2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "react-use",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Collection of React Hooks",
   "main": "lib/index.js",
   "files": [