feat: port the media file player example to the client API (#399)

* Let a local track's close be waited for

LocalTrack.closeAsync completes once the native track is released, after
which a source it was made over may be closed.

* Port the media file player example to the client API

One runtime in the CUSTOM audio mode replaces the two factories, a loopback
signaling the hand-rolled offer, answer and candidate exchange, and the
Swing VideoView the example's own panel. Statistics come from onStats, and
a Record button records the received tracks with MediaRecorder.

Author: devopvoid

design/client-api.md

@@ -811,4 +811,5 @@ Next:
 - phase 2 is done: `Whip.to(...).publish(rtc)` and
   `Whep.from(...).play(rtc)` return sessions over `HttpURLConnection` (Java 8), and `VideoView` is in
   `dev.onvoid.webrtc.client.swing`;
-- porting the existing examples (phases 2 and 3).
+- porting the existing examples (phases 2 and 3); `MediaFilePlayerExample` is ported, with a
+  Record button, and `LocalTrack.closeAsync()` came with it.

docs/guide/client-api.md

@@ -306,7 +306,7 @@ peer.addTrack(rtc.media().audioTrack("movie", file.getAudioSource()));
 file.play();
 ```
 
-Create the runtime before the file: the runtime loads the native library that the file's sources need. The sources belong to the `MediaFileSource`, not to the tracks, so close the runtime, or the tracks, before the file. The file's audio source is pushed audio, so the runtime needs the `CUSTOM` or `HEADLESS` audio mode.
+Create the runtime before the file: the runtime loads the native library that the file's sources need. The sources belong to the `MediaFileSource`, not to the tracks, so close the runtime, or the tracks, before the file: `track.closeAsync()` returns a future that completes once the track let go of its source. The file's audio source is pushed audio, so the runtime needs the `CUSTOM` or `HEADLESS` audio mode.
 
 ### Pushing Video and Audio
 

docs/guide/examples.md

@@ -100,16 +100,19 @@ mvn exec:java -D"exec.mainClass=dev.onvoid.webrtc.examples.MediaFileExample" -D"
 
 ## Media File Player
 
-The [`MediaFilePlayerExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/MediaFilePlayerExample.java) is a Swing application that sends a media file, or a live RTSP stream, from one peer connection to another in the same process, then shows the received video and plays the received audio in sync. Start and Stop buttons set up and tear down the whole session.
+The [`MediaFilePlayerExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/MediaFilePlayerExample.java) is a Swing application built on the [Client API](/guide/client-api). It sends a media file, or a live RTSP stream, from one peer to another in the same process, then shows the received video and plays the received audio in sync, and records what is received. Start and Stop buttons set up and tear down the whole session, and Record starts and stops a recording.
 
 **Key features demonstrated:**
-- Connecting two peer connections in one application, without a signaling server
-- Using one factory with a dummy audio layer to send the file, and another with the platform audio layer to play what is received
+- Sending the sources of a `MediaFileSource` as client API tracks, with `videoTrack` and `audioTrack`
+- Connecting two peers in one application through a loopback signaling
+- Using one runtime in the `CUSTOM` audio mode, which sends the file's audio and plays what is received
+- Running the peers' handlers on the Swing event dispatch thread
 - Keeping audio and video in sync by sending both tracks in the same media stream
-- Raising the video sender's `maxBitrate` above WebRTC's default, so a high-resolution file is not held to a fraction of its size
-- Rendering received video frames in a Swing component with `VideoBufferConverter`
-- Showing the source's format, the playback position, and live receive metrics (codec, resolution, frame rate, bitrate, packet loss, jitter, audio level) read from `getStats()`
-- Releasing senders, peer connections, tracks and the source in order on Stop
+- Raising the video sender's maximum bitrate once it is connected, so a high-resolution file is not held to a fraction of its size
+- Rendering received video in the Swing `VideoView`
+- Showing the source's format, the playback position, and live receive metrics (codec, resolution, frame rate, bitrate, packet loss, jitter, audio level) read from `onStats`
+- Recording the received tracks into a Matroska file with `MediaRecorder`
+- Closing the peers, then the tracks, then the source on Stop
 
 ::: info
 Like the [Media File](#media-file) example, this one needs the `webrtc-java-media` module. The source argument is optional; a file can also be chosen from the window, or a stream URL typed into it. A stream URL's credentials are never shown, and the Loop box is disabled while a live stream plays, since it has no length to start over from.