From c807bca8beb64defa42ba05563a08d37094f5d37 Mon Sep 17 00:00:00 2001 From: Alex Andres Date: Mon, 9 Nov 2026 00:26:08 +0100 Subject: [PATCH 1/3] feat: record into rotating segments and keep a replay buffer MediaRecorder can split a recording into segments that each begin at a key frame, ended by duration or size, keeping as many as SegmentOptions say. ReplayBuffer keeps the last seconds in memory and saves them on demand. --- README.md | 2 +- docs/guide/index.md | 2 +- docs/guide/media/media-recording.md | 62 ++ .../src/main/cpp/include/JNI_MediaRecorder.h | 24 + .../src/main/cpp/include/JNI_RecordingProbe.h | 36 + .../src/main/cpp/include/JNI_WriteFault.h | 4 +- .../cpp/include/media/JavaRecorderObserver.h | 6 + .../main/cpp/include/media/MediaRecorder.h | 161 +++- .../cpp/include/media/MediaRecorderObserver.h | 13 + .../main/cpp/include/media/RecorderOutput.h | 123 +++ .../main/cpp/include/media/RecorderTrack.h | 41 +- .../src/main/cpp/src/JNI_MediaRecorder.cpp | 118 ++- .../src/main/cpp/src/JNI_RecordingProbe.cpp | 109 +++ .../src/main/cpp/src/JNI_WriteFault.cpp | 4 +- .../cpp/src/media/JavaRecorderObserver.cpp | 55 ++ .../src/main/cpp/src/media/MediaRecorder.cpp | 901 ++++++++++++++++-- .../src/main/cpp/src/media/RecorderOutput.cpp | 278 ++++++ .../src/main/cpp/src/media/RecorderTrack.cpp | 91 +- .../webrtc/media/recorder/MediaRecorder.java | 327 ++++++- .../media/recorder/MediaRecorderListener.java | 15 + .../media/recorder/MediaRecorderSegment.java | 114 +++ .../webrtc/media/recorder/ReplayBuffer.java | 284 ++++++ .../webrtc/media/recorder/SegmentOptions.java | 401 ++++++++ .../webrtc/media/recorder/RecordingProbe.java | 99 ++ .../media/recorder/ReplayBufferTest.java | 239 +++++ .../media/recorder/SegmentedRecorderTest.java | 662 +++++++++++++ .../webrtc/media/recorder/TestCall.java | 17 + .../webrtc/media/recorder/WriteFault.java | 13 +- 28 files changed, 4035 insertions(+), 166 deletions(-) create mode 100644 webrtc-media/src/main/cpp/include/JNI_RecordingProbe.h create mode 100644 webrtc-media/src/main/cpp/include/media/RecorderOutput.h create mode 100644 webrtc-media/src/main/cpp/src/JNI_RecordingProbe.cpp create mode 100644 webrtc-media/src/main/cpp/src/media/RecorderOutput.cpp create mode 100644 webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderSegment.java create mode 100644 webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/ReplayBuffer.java create mode 100644 webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/SegmentOptions.java create mode 100644 webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/RecordingProbe.java create mode 100644 webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/ReplayBufferTest.java create mode 100644 webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/SegmentedRecorderTest.java diff --git a/README.md b/README.md index 525f484a6..2b0d4261a 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ The library provides a comprehensive set of Java classes that map to the WebRTC **Optional modules** - **[Media playback](https://jrtc.dev/guide/media/media-files)** (`webrtc-java-media`) - Stream video and audio files or RTSP sources into a call, decoded with FFmpeg -- **[Call recording](https://jrtc.dev/guide/media/media-recording)** (`webrtc-java-media`) - Save what a call sends or receives into MKV, WebM or MP4 files, without re-encoding +- **[Call recording](https://jrtc.dev/guide/media/media-recording)** (`webrtc-java-media`) - Save what a call sends or receives into MKV, WebM or MP4 files, without re-encoding, as one file, rotating segments, or a replay buffer of the last seconds **Platforms** diff --git a/docs/guide/index.md b/docs/guide/index.md index e3c06cfb3..8d32c6e1c 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -8,7 +8,7 @@ This section provides detailed guides for various features of the webrtc-java li - [Bitrate and Framerate Constraints](/guide/media/constraints) - Controlling media quality - [Send-only and Receive-only](/guide/media/directionality) - Configure transceiver directions (send-only, receive-only or inactive) - [Media Files](/guide/media/media-files) - Sending video and audio files instead of a camera and microphone -- [Media Recording](/guide/media/media-recording) - Recording what a call sends or receives into a media file, without re-encoding +- [Media Recording](/guide/media/media-recording) - Recording what a call sends or receives into a media file, into rotating segments, or into a replay buffer, without re-encoding ## Audio diff --git a/docs/guide/media/media-recording.md b/docs/guide/media/media-recording.md index 1cd90e9f3..a45225163 100644 --- a/docs/guide/media/media-recording.md +++ b/docs/guide/media/media-recording.md @@ -5,6 +5,8 @@ This guide explains how to record what a peer connection sends or receives into - Recording senders and receivers - Replacing a file that exists - Choosing the container +- Splitting a recording into segments, and how many to keep +- Keeping the last seconds in memory and saving them on demand - Following a recording with a listener - How tracks are started, timed and left out - Measuring what a recording lost @@ -92,6 +94,66 @@ A name FFmpeg does not know gets Matroska. A track whose codec the file cannot h Matroska has no codec ID of its own for G.711, so it is stored as Windows audio (`A_MS/ACM`), the way FFmpeg itself stores it. Players built on FFmpeg, such as VLC and mpv, play it; some others do not. +## Recording in Segments + +For recordings that run for hours, such as surveillance or support sessions, a recorder can split the recording into segments: files that each play on their own, ended by duration or size, of which it keeps as many as asked. + +```java +SegmentOptions segments = SegmentOptions.builder(Paths.get("recordings", "camera-%05d.mkv")) + .maxDuration(Duration.ofMinutes(10)) // end a segment after 10 minutes, + .maxSize(512L * 1024 * 1024) // or once it holds 512 MB + .maxTotalSize(20L * 1024 * 1024 * 1024) // keep the newest 20 GB + .build(); + +try (MediaRecorder recorder = new MediaRecorder(segments)) { + recorder.setListener(new MediaRecorderListener() { + + @Override + public void onSegmentFinished(MediaRecorderSegment segment) { + upload(segment.getFile()); + } + }); + recorder.addTrack(videoReceiver); + recorder.addTrack(audioReceiver); + recorder.start(); + + // ... +} +``` + +The file name of the pattern holds the segment's number as `%d`, or zero-padded as `%05d`; a literal percent sign is `%%`. The extension picks the container of all segments, as for a single file. Numbering goes on from the highest number already in the directory, so a recorder started again continues after the last segment, and a segment never empties a file that exists: its number is skipped instead. + +- **Every segment begins at a key frame.** Once a segment has reached its duration or size, the recorder asks the video tracks for key frames, and the next segment begins with the first that arrives, usually a fraction of a second later. A segment is therefore somewhat longer or larger than the limit. Without video, a segment ends right at the limit. +- **Several video tracks lose nothing.** A video track whose key frame comes after the one that began the next segment goes on in the segment before until then, so neither file has a gap. One that sends no key frame within three seconds starts the new segment at its next. +- **Each segment starts at zero.** Its tracks are shifted by the same amount, so they stay in sync, and one segment follows the other without a gap. `MediaRecorderSegment.getStart()` tells where a segment lies in the recording. +- **A codec change starts a segment.** A file cannot change the codec of a stream, so a track that changes its codec, e.g. after a renegotiation, goes on in the next segment, which begins as soon as the new codec is known. A single file leaves such a track out from then on instead. +- **A slow disk holds nothing up.** Segments are finished and opened by the recorder's writer thread, with the frames queuing up meanwhile as always, and old segments are deleted on the listener's thread. + +`onSegmentFinished` hears of every segment once it is finished and closed, the last one when the recorder stops. Right after it returns, the oldest segments beyond `maxSegments` or `maxTotalSize` are deleted, so a segment to be kept for longer has to be moved or copied by then. The newest segment is always kept, and the one being written does not count toward `maxTotalSize`, so the recording takes up to that much and one segment more. `getSegments()` lists the segments that are kept, and `getFile()` returns the last one finished. + +A write that fails, e.g. because the disk is full, ends the recording as it does for a single file. The segment it happened in is kept as `PARTIAL` if it holds media; one that failed before any went into it is deleted. + +## Replay Buffer + +A `ReplayBuffer` keeps the last seconds of a call in memory and writes them into a file only when asked, for "save the last 30 seconds": + +```java +try (ReplayBuffer buffer = new ReplayBuffer(Duration.ofSeconds(30))) { + buffer.addTrack(videoReceiver); + buffer.addTrack(audioReceiver); + buffer.start(); + + // ... something happens worth keeping ... + + buffer.save(Paths.get("incident.mkv")) + .thenAccept(replay -> System.out.println("Saved " + replay.getDuration())); +} +``` + +`save` creates the file at once, refusing one that exists, and the buffer's own thread writes the replay, while the buffer goes on taking frames. The future completes on the listener's thread with a `MediaRecorderSegment`, or exceptionally if nothing could be saved, and the file is then deleted. A buffer can save any number of replays, in any container; a track whose codec the container cannot hold is left out of that replay with a warning. + +A replay begins with a key frame of every video track: the last one before the window, so a replay holds at least the window, and a few seconds more. Since WebRTC rarely sends key frames of its own accord, the buffer asks its video tracks for one every third of the window, at least every two seconds and at most every ten. Besides the window, the buffer holds at most 256 MB, or what its constructor is given; beyond that, the oldest frames go first, and a replay is shorter. A track that changes its codec is kept with the new codec from then on. + ## Following a Recording A `MediaRecorderListener` hears when the file begins, what was left out, and whether writing failed: diff --git a/webrtc-media/src/main/cpp/include/JNI_MediaRecorder.h b/webrtc-media/src/main/cpp/include/JNI_MediaRecorder.h index 415310642..ebd3465f9 100644 --- a/webrtc-media/src/main/cpp/include/JNI_MediaRecorder.h +++ b/webrtc-media/src/main/cpp/include/JNI_MediaRecorder.h @@ -30,6 +30,22 @@ extern "C" { JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_create (JNIEnv *, jobject, jstring, jlong); + /* + * Class: dev_onvoid_webrtc_media_recorder_MediaRecorder + * Method: createSegments + * Signature: (Ljava/lang/String;Ljava/lang/String;IJJJJ)J + */ + JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_createSegments + (JNIEnv *, jobject, jstring, jstring, jint, jlong, jlong, jlong, jlong); + + /* + * Class: dev_onvoid_webrtc_media_recorder_MediaRecorder + * Method: createReplay + * Signature: (JJJ)J + */ + JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_createReplay + (JNIEnv *, jobject, jlong, jlong, jlong); + /* * Class: dev_onvoid_webrtc_media_recorder_MediaRecorder * Method: addTrack @@ -62,6 +78,14 @@ extern "C" { JNIEXPORT jlongArray JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_stats (JNIEnv *, jclass, jlong); + /* + * Class: dev_onvoid_webrtc_media_recorder_MediaRecorder + * Method: saveReplay + * Signature: (JILjava/lang/String;)Z + */ + JNIEXPORT jboolean JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_saveReplay + (JNIEnv *, jclass, jlong, jint, jstring); + /* * Class: dev_onvoid_webrtc_media_recorder_MediaRecorder * Method: dispose diff --git a/webrtc-media/src/main/cpp/include/JNI_RecordingProbe.h b/webrtc-media/src/main/cpp/include/JNI_RecordingProbe.h new file mode 100644 index 000000000..0725e6541 --- /dev/null +++ b/webrtc-media/src/main/cpp/include/JNI_RecordingProbe.h @@ -0,0 +1,36 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#include +/* Header for class dev_onvoid_webrtc_media_recorder_RecordingProbe */ + +#ifndef _Included_dev_onvoid_webrtc_media_recorder_RecordingProbe +#define _Included_dev_onvoid_webrtc_media_recorder_RecordingProbe +#ifdef __cplusplus +extern "C" { +#endif + /* + * Class: dev_onvoid_webrtc_media_recorder_RecordingProbe + * Method: streams + * Signature: (Ljava/lang/String;)[J + */ + JNIEXPORT jlongArray JNICALL Java_dev_onvoid_webrtc_media_recorder_RecordingProbe_streams + (JNIEnv *, jclass, jstring); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/webrtc-media/src/main/cpp/include/JNI_WriteFault.h b/webrtc-media/src/main/cpp/include/JNI_WriteFault.h index 3249f740a..8d888307e 100644 --- a/webrtc-media/src/main/cpp/include/JNI_WriteFault.h +++ b/webrtc-media/src/main/cpp/include/JNI_WriteFault.h @@ -33,10 +33,10 @@ extern "C" { /* * Class: dev_onvoid_webrtc_media_recorder_WriteFault * Method: failHeader - * Signature: ()V + * Signature: (I)V */ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_media_recorder_WriteFault_failHeader - (JNIEnv *, jclass); + (JNIEnv *, jclass, jint); /* * Class: dev_onvoid_webrtc_media_recorder_WriteFault diff --git a/webrtc-media/src/main/cpp/include/media/JavaRecorderObserver.h b/webrtc-media/src/main/cpp/include/media/JavaRecorderObserver.h index 29d4ffeed..899e36fac 100644 --- a/webrtc-media/src/main/cpp/include/media/JavaRecorderObserver.h +++ b/webrtc-media/src/main/cpp/include/media/JavaRecorderObserver.h @@ -46,6 +46,10 @@ namespace ffmpeg void OnWarning(const std::string & message) override; void OnError(const std::string & message) override; void OnKeyFrameNeeded(int track) override; + void OnSegmentFinished(int64_t index, const std::string & path, + int64_t start_us, int64_t duration_us, int result) override; + void OnReplaySaved(int id, int result, int64_t start_us, + int64_t duration_us, const std::string & error) override; private: // Calls a void Java method taking one String. @@ -69,6 +73,8 @@ namespace ffmpeg jmethodID on_warning_ = nullptr; jmethodID on_error_ = nullptr; jmethodID on_key_frame_needed_ = nullptr; + jmethodID on_segment_finished_ = nullptr; + jmethodID on_replay_saved_ = nullptr; }; } diff --git a/webrtc-media/src/main/cpp/include/media/MediaRecorder.h b/webrtc-media/src/main/cpp/include/media/MediaRecorder.h index 577219d8e..ecb1ba9a7 100644 --- a/webrtc-media/src/main/cpp/include/media/MediaRecorder.h +++ b/webrtc-media/src/main/cpp/include/media/MediaRecorder.h @@ -18,6 +18,7 @@ #define WEBRTC_JAVA_MEDIA_MEDIA_RECORDER_H_ #include "media/MediaRecorderObserver.h" +#include "media/RecorderOutput.h" #include "media/RecorderTrack.h" #include "webrtc_java_api.h" @@ -51,6 +52,11 @@ namespace ffmpeg // header is written once every track has described itself, or once the // tracks that did have waited long enough for the rest; frames that come // before are held back until then. + // + // A recorder writes one file, or a series of segments, each of which is + // a file of its own that starts at a key frame of every video track; or + // it keeps the last seconds in memory, from which a replay is saved on + // demand. class MediaRecorder { public: @@ -82,6 +88,31 @@ namespace ffmpeg int64_t dropped_awaiting_key_frame = 0; }; + // Where segments go and when one ends. + struct SegmentConfig + { + // A segment's file name is the prefix, its index in decimal, + // zero-padded to the width, and the suffix, whose extension + // picks the container. + std::string prefix; + std::string suffix; + int width = 1; + int64_t first_index = 0; + // A segment ends at the next key frame once it lasts this + // long, or holds this much; zero for no limit. + int64_t max_duration_us = 0; + int64_t max_bytes = 0; + }; + + // What a replay buffer keeps. + struct ReplayConfig + { + // How far back a replay reaches. + int64_t window_us = 0; + // The most it holds, beyond which the oldest frames go. + int64_t max_bytes = 0; + }; + struct Stats { // The most that ever waited for the writer. @@ -90,8 +121,15 @@ namespace ffmpeg std::vector tracks; }; + // Records into one file. MediaRecorder(const webrtc_java_api * api, std::string path); + // Records into a series of segments. + MediaRecorder(const webrtc_java_api * api, SegmentConfig segments); + + // Keeps the last seconds for replays. + MediaRecorder(const webrtc_java_api * api, ReplayConfig replay); + // Stops the recording if it still runs. ~MediaRecorder(); @@ -102,7 +140,8 @@ namespace ffmpeg void SetObserver(std::unique_ptr observer); // Opens the output file, choosing the container from its name. - // Returns 0 or a negative AVERROR. + // Segments are opened as they begin, and replays as they are + // saved. Returns 0 or a negative AVERROR. int Open(); // Adds a sender or receiver to record, by the handle that @@ -125,7 +164,29 @@ namespace ffmpeg // What was lost so far. Stays available once stopped. Stats GetStats(); + // Saves what the buffer holds of the last seconds into the given + // file, which exists and is empty, and reports it to the + // observer with the given id. Returns false if the buffer takes + // no more requests, because it is stopped or failed, and the + // observer hears nothing. + bool SaveReplay(int id, std::string path); + private: + enum class Mode + { + kFile, + kSegments, + kReplay + }; + + struct SaveRequest + { + int id = 0; + std::string path; + }; + + MediaRecorder(const webrtc_java_api * api, Mode mode, std::string path); + // What the observer callback knows about a track. Guarded by // mutex_, since WebRTC calls in on threads of its own. struct Input @@ -181,7 +242,58 @@ namespace ffmpeg void Abort() noexcept; void Handle(RecordedFrame frame); - void Write(RecordedFrame & frame); + + // A track that changed its codec is described anew: it goes on in + // the next segment, or in the replays from then on. + void ChangeCodec(RecorderTrack & track, const RecordedFrame & frame); + + // Writes the frame into the given file, and fails the recording + // if that does. + void Write(RecorderOutput & output, RecordedFrame & frame); + + // Where a frame goes once the file or the first segment began. + void Route(RecordedFrame & frame); + void RouteSegment(RecordedFrame & frame); + + // Opens the next segment, starting at the given point of the + // timeline, with a stream for every ready track. On failure the + // recording is failed, and false returned. + bool OpenSegment(int64_t start_us); + + // Ends the segment that writes the frame, and begins the next. + void Rotate(const RecordedFrame & frame); + void DueRotation(); + + // Ends the segment before once its video tracks have all moved + // on, or waited long enough, and keeps asking for the key frames + // the segments wait for. + void CheckSegments(int64_t now_us); + + // Whether a video track still writes into the segment before. + bool Draining() const; + + std::string SegmentPath(int64_t index) const; + + // Finishes and closes a segment, and reports it. + void FinishSegment(std::unique_ptr segment); + + // Asks every video track that is ready for a key frame. + void RequestKeyFrames(); + + // Counts a frame that was dropped on the writer thread on the way + // to its track's next key frame. + void CountAwaitingKeyFrame(int track); + + bool AnyVideoReady() const; + bool SegmentLimitReached() const; + + // Replay buffer. + void Buffer(RecordedFrame frame); + void TrimBuffer(); + void RemoveFromBuffer(int track); + void RequestReplayKeyFrames(int64_t now_us); + void Save(const SaveRequest & request); + void SaveFailed(const SaveRequest & request, const std::string & message, int error); // Writes the header once the tracks are known, or once waiting // for the rest is no longer worth it. Returns whether the header @@ -193,7 +305,9 @@ namespace ffmpeg // Closes the file if it is open, and fails the recording if that // does. void Close(); - void Fail(const std::string & message, int error); + + // Fails the recording, and marks the file that failed, if any. + void Fail(const std::string & message, int error, RecorderOutput * output = nullptr); void Warn(const std::string & message); // Called with the lock held; the requests are sent once it is @@ -201,15 +315,51 @@ namespace ffmpeg void CollectKeyFrameRequestsLocked(std::vector * tracks, int64_t now_us); const webrtc_java_api * api_; + const Mode mode_; + // The file, or what the files are named after, for reports. const std::string path_; // Made in advance, since a writer that ran out of memory may not // get any to describe that. + const std::string subject_; const std::string out_of_memory_error_; std::unique_ptr observer_; + SegmentConfig segments_; + ReplayConfig replay_; + + // The container that tracks are checked against; null for a + // replay buffer, whose replays may go into any. + const AVOutputFormat * format_ = nullptr; + // The writer thread's, once Start() ran. - AVFormatContext * context_ = nullptr; + // The file, or the segment that is written. + std::unique_ptr output_; + // The segment before, which takes the frames of the video tracks + // that have not reached a key frame in the next one yet. + std::unique_ptr draining_; + int64_t next_index_ = 0; + int64_t drain_started_us_ = 0; + bool rotation_due_ = false; + int64_t rotation_due_us_ = 0; + // By track: whether a video track has begun in output_. + std::vector switched_; + // By track: whether the track waits for the next segment, after + // it changed its codec. + std::vector awaiting_segment_; + bool skipped_existing_ = false; + + // The replay buffer, in the order the frames arrived, and the + // times of the key frames each video track has in it. + std::deque ring_; + size_t ring_bytes_ = 0; + std::vector> key_times_; + // By track: when its last key frame arrived, in the clock of the + // frames, and where its last frame lies on the timeline. + std::vector last_key_us_; + std::vector last_frame_us_; + int64_t key_frame_interval_us_ = 0; + std::vector> tracks_; std::deque pending_; size_t pending_bytes_ = 0; @@ -233,6 +383,9 @@ namespace ffmpeg size_t max_queued_bytes_ = 0; // What the callbacks have to report, which the writer does. std::vector pending_warnings_; + std::vector save_requests_; + // Set once the writer takes no more save requests. + bool writer_ended_ = false; // Wakes the writer for something other than frames. bool poke_ = false; bool accepting_ = false; diff --git a/webrtc-media/src/main/cpp/include/media/MediaRecorderObserver.h b/webrtc-media/src/main/cpp/include/media/MediaRecorderObserver.h index f0a774e67..3c12e986b 100644 --- a/webrtc-media/src/main/cpp/include/media/MediaRecorderObserver.h +++ b/webrtc-media/src/main/cpp/include/media/MediaRecorderObserver.h @@ -17,6 +17,7 @@ #ifndef WEBRTC_JAVA_MEDIA_MEDIA_RECORDER_OBSERVER_H_ #define WEBRTC_JAVA_MEDIA_MEDIA_RECORDER_OBSERVER_H_ +#include #include namespace ffmpeg @@ -41,6 +42,18 @@ namespace ffmpeg // The given video track waits for a key frame, and the sender or // receiver it records should be asked for one. virtual void OnKeyFrameNeeded(int track) = 0; + + // A segment was finished and closed, or failed before any media + // went into it. The result is a MediaRecorder::Result: complete, + // partial, or failed for a file that holds nothing to keep. + virtual void OnSegmentFinished(int64_t index, const std::string & path, + int64_t start_us, int64_t duration_us, int result) = 0; + + // A replay asked for with the given id was saved, or not. The + // result is a MediaRecorder::Result; the error says what went + // wrong, and is empty if nothing did. + virtual void OnReplaySaved(int id, int result, int64_t start_us, + int64_t duration_us, const std::string & error) = 0; }; } diff --git a/webrtc-media/src/main/cpp/include/media/RecorderOutput.h b/webrtc-media/src/main/cpp/include/media/RecorderOutput.h new file mode 100644 index 000000000..4f12bd9ff --- /dev/null +++ b/webrtc-media/src/main/cpp/include/media/RecorderOutput.h @@ -0,0 +1,123 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef WEBRTC_JAVA_MEDIA_RECORDER_OUTPUT_H_ +#define WEBRTC_JAVA_MEDIA_RECORDER_OUTPUT_H_ + +#include "media/RecorderTrack.h" + +#include +#include +#include + +extern "C" { +#include +} + +namespace ffmpeg +{ + // One file a recorder writes: the whole recording, one of its segments, + // or a replay saved from its buffer. + // + // Frames arrive placed on the timeline of the recording, and the file + // starts at a point of that timeline of its own, so that every file + // begins near zero however late in the recording it was started. All + // streams are shifted by the same amount, which keeps them in sync. + // + // Used on the recorder's writer thread only. + class RecorderOutput + { + public: + // start_us is the point of the timeline the file begins at; index + // is the number of the segment or replay, for reports. + RecorderOutput(std::string path, int64_t start_us, int64_t index); + + // Frees the file without finishing it, closing it if still open. + ~RecorderOutput(); + + RecorderOutput(const RecorderOutput &) = delete; + RecorderOutput & operator=(const RecorderOutput &) = delete; + + // Opens the file, choosing the container from its name; a name + // FFmpeg cannot place gets Matroska. An exclusive open refuses a + // file that exists with AVERROR(EEXIST). Returns 0 or a negative + // AVERROR. + int Open(bool exclusive); + + const std::string & GetPath() const; + int64_t GetIndex() const; + int64_t GetStartUs() const; + const AVOutputFormat * GetFormat() const; + + // Adds a stream for the ready track. Before WriteHeader() only. + int AddStream(const RecorderTrack & track); + bool HasStream(int track) const; + bool HasStreams() const; + + int WriteHeader(); + bool IsHeaderWritten() const; + + // Writes the frame into the stream of its track. A frame to keep + // has a reference of its packet written, otherwise the packet is + // handed over and left blank. + int Write(RecordedFrame & frame, bool keep); + + // Finishes the file; the trailer of a file whose header was never + // written is skipped. + int WriteTrailer(); + + // Closes the file if it is open. Flushes what is still buffered. + int Close(); + + // Whether a packet went into the file. + bool HasMedia() const; + + // The span from the start to the last frame written. + int64_t GetDurationUs() const; + + // About what the file takes on disk: the header and the packets + // written, without what the container adds around them. + int64_t GetBytes() const; + + // Marks the file as incomplete, after a write into it failed. + void SetFailed(); + bool IsFailed() const; + + private: + struct Stream + { + AVStream * stream = nullptr; + int clock_rate = 0; + int64_t last_pts = -1; + }; + + const std::string path_; + const int64_t start_us_; + const int64_t index_; + + AVFormatContext * context_ = nullptr; + // By track index; a track without a stream has none. + std::vector streams_; + + bool header_written_ = false; + bool failed_ = false; + int64_t packets_ = 0; + int64_t bytes_ = 0; + int64_t last_us_ = 0; + }; +} + +#endif diff --git a/webrtc-media/src/main/cpp/include/media/RecorderTrack.h b/webrtc-media/src/main/cpp/include/media/RecorderTrack.h index 9687d3538..36e6e1a0e 100644 --- a/webrtc-media/src/main/cpp/include/media/RecorderTrack.h +++ b/webrtc-media/src/main/cpp/include/media/RecorderTrack.h @@ -54,6 +54,11 @@ namespace ffmpeg bool key_frame = false; int width = 0; int height = 0; + // Where the frame lies on the timeline of the recording, which + // RecorderTrack::Timestamp() sets: in the clock of its track, and in + // microseconds. + int64_t pts = 0; + int64_t timeline_us = 0; }; // One recorded sender or receiver, as a stream in the output file. @@ -86,22 +91,34 @@ namespace ffmpeg int GetIndex() const; Status GetStatus() const; bool IsVideo() const; + int GetClockRate() const; - // Learns what it can about the stream from the frame. When this - // makes the track unsupported, the message says why. + // The MIME type of the codec the track was described with. + const std::string & GetMimeType() const; + + // Learns what it can about the stream from the frame. A format of + // null accepts every codec WebRTC sends, for a file that is not + // known yet. When this makes the track unsupported, the message + // says why. Status Probe(const RecordedFrame & frame, const AVOutputFormat * format, std::string * message); - // Adds the stream of a ready track to the output. - int CreateStream(AVFormatContext * context); + // Whether a file of the given format can hold the stream of a + // ready track. If not, the message says why. + bool CanBeHeldBy(const AVOutputFormat * format, std::string * message) const; - // The stream in the output, or null while there is none. - AVStream * GetStream() const; + // Forgets what it learned, for a stream that changed its codec, + // which is then described anew from its next frames. + void Reset(); - // Turns the frame into a packet of this track's stream, stamped - // with its presentation time. start_us is when recording started, - // in the clock of RecordedFrame::time_us. - AVPacket * Stamp(RecordedFrame & frame, int64_t start_us); + // Adds the stream of a ready track to the output. + int CreateStream(AVFormatContext * context, AVStream ** stream) const; + + // Places the frame on the timeline of the recording, setting its + // pts and timeline_us. start_us is when recording started, in the + // clock of RecordedFrame::time_us. Called for every frame of the + // track, in the order they arrived. + void Timestamp(RecordedFrame & frame, int64_t start_us); private: bool DescribeVideo(const RecordedFrame & frame); @@ -124,8 +141,7 @@ namespace ffmpeg int height_ = 0; int channels_ = 0; std::vector extradata_; - - AVStream * stream_ = nullptr; + std::string mime_type_; // Timing. RTP timestamps are exact within a stream, but start at a // random value, so a track is anchored on the clock once and @@ -135,7 +151,6 @@ namespace ffmpeg uint32_t last_rtp_ = 0; int64_t rtp_offset_ = 0; int64_t base_pts_ = 0; - int64_t last_pts_ = -1; }; } diff --git a/webrtc-media/src/main/cpp/src/JNI_MediaRecorder.cpp b/webrtc-media/src/main/cpp/src/JNI_MediaRecorder.cpp index ee1331bef..64f423b88 100644 --- a/webrtc-media/src/main/cpp/src/JNI_MediaRecorder.cpp +++ b/webrtc-media/src/main/cpp/src/JNI_MediaRecorder.cpp @@ -32,41 +32,48 @@ namespace { return reinterpret_cast(handle); } -} -JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_create -(JNIEnv * env, jobject caller, jstring jPath, jlong tableAddress) -{ - return ffmpeg::CallFromJava(env, 0, [&]() -> jlong { + // The table of the webrtc-java API, or null with an IOException thrown. + const webrtc_java_api * ApiOf(JNIEnv * env, jlong tableAddress) + { const webrtc_java_api * api = reinterpret_cast(tableAddress); std::string apiError = ffmpeg::CheckApi(api); if (!apiError.empty()) { ffmpeg::ThrowIOException(env, apiError); - return 0; + return nullptr; } - std::string path; - - { - ffmpeg::JavaStringChars chars(env, jPath); + return api; + } - if (chars.get() == nullptr) { - return 0; - } + // Copies a Java string as UTF-8. Returns false with an exception + // pending if it cannot. + bool CopyString(JNIEnv * env, jstring string, std::string * utf8) + { + ffmpeg::JavaStringChars chars(env, string); - path = chars.utf8(); + if (chars.get() == nullptr) { + return false; } - auto recorder = std::make_unique(api, path); + *utf8 = chars.utf8(); + + return true; + } + // Opens the recorder and gives it the Java recorder to report to, or + // throws, naming what it was to record to. + jlong Finish(JNIEnv * env, jobject caller, std::unique_ptr recorder, + const std::string & target) + { int result = recorder->Open(); if (result < 0) { recorder.reset(); - ffmpeg::ThrowIOException(env, "Opening " + path + " for recording failed: " + ffmpeg::ErrorText(result)); + ffmpeg::ThrowIOException(env, "Opening " + target + " for recording failed: " + ffmpeg::ErrorText(result)); return 0; } @@ -74,6 +81,67 @@ JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_crea recorder->SetObserver(std::make_unique(env, caller)); return reinterpret_cast(recorder.release()); + } +} + +JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_create +(JNIEnv * env, jobject caller, jstring jPath, jlong tableAddress) +{ + return ffmpeg::CallFromJava(env, 0, [&]() -> jlong { + const webrtc_java_api * api = ApiOf(env, tableAddress); + std::string path; + + if (api == nullptr || !CopyString(env, jPath, &path)) { + return 0; + } + + return Finish(env, caller, std::make_unique(api, path), path); + }); +} + +JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_createSegments +(JNIEnv * env, jobject caller, jstring jPrefix, jstring jSuffix, jint width, jlong firstIndex, + jlong maxDurationUs, jlong maxBytes, jlong tableAddress) +{ + return ffmpeg::CallFromJava(env, 0, [&]() -> jlong { + const webrtc_java_api * api = ApiOf(env, tableAddress); + + if (api == nullptr) { + return 0; + } + + ffmpeg::MediaRecorder::SegmentConfig segments; + + if (!CopyString(env, jPrefix, &segments.prefix) || !CopyString(env, jSuffix, &segments.suffix)) { + return 0; + } + + segments.width = static_cast(width); + segments.first_index = static_cast(firstIndex); + segments.max_duration_us = static_cast(maxDurationUs); + segments.max_bytes = static_cast(maxBytes); + + const std::string target = segments.prefix + "*" + segments.suffix; + + return Finish(env, caller, std::make_unique(api, std::move(segments)), target); + }); +} + +JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_createReplay +(JNIEnv * env, jobject caller, jlong windowUs, jlong maxBytes, jlong tableAddress) +{ + return ffmpeg::CallFromJava(env, 0, [&]() -> jlong { + const webrtc_java_api * api = ApiOf(env, tableAddress); + + if (api == nullptr) { + return 0; + } + + ffmpeg::MediaRecorder::ReplayConfig replay; + replay.window_us = static_cast(windowUs); + replay.max_bytes = static_cast(maxBytes); + + return Finish(env, caller, std::make_unique(api, replay), "a replay buffer"); }); } @@ -143,6 +211,24 @@ JNIEXPORT jlongArray JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder }); } +JNIEXPORT jboolean JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_saveReplay +(JNIEnv * env, jclass caller, jlong handle, jint id, jstring jPath) +{ + if (handle == 0) { + return JNI_FALSE; + } + + return ffmpeg::CallFromJava(env, JNI_FALSE, [&]() -> jboolean { + std::string path; + + if (!CopyString(env, jPath, &path)) { + return JNI_FALSE; + } + + return RecorderOf(handle)->SaveReplay(static_cast(id), std::move(path)) ? JNI_TRUE : JNI_FALSE; + }); +} + JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_media_recorder_MediaRecorder_dispose (JNIEnv * env, jclass caller, jlong handle) { diff --git a/webrtc-media/src/main/cpp/src/JNI_RecordingProbe.cpp b/webrtc-media/src/main/cpp/src/JNI_RecordingProbe.cpp new file mode 100644 index 000000000..b9787d54b --- /dev/null +++ b/webrtc-media/src/main/cpp/src/JNI_RecordingProbe.cpp @@ -0,0 +1,109 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#include "JNI_RecordingProbe.h" +#include "media/ErrorText.h" +#include "media/JniBoundary.h" + +#include +#include +#include + +extern "C" { +#include +} + +// The Java class this belongs to exists in the tests only, so that nothing but +// them can reach it. It reads a recorded file packet by packet, which shows +// what a reader of the file's header alone does not: where each stream begins +// and whether it begins at a key frame. + +namespace +{ + // What is reported per stream, in the order RecordingProbe reads it. + constexpr size_t kValues = 5; +} + +JNIEXPORT jlongArray JNICALL Java_dev_onvoid_webrtc_media_recorder_RecordingProbe_streams +(JNIEnv * env, jclass caller, jstring jPath) +{ + return ffmpeg::CallFromJava(env, nullptr, [&]() -> jlongArray { + std::string path; + + { + ffmpeg::JavaStringChars chars(env, jPath); + + if (chars.get() == nullptr) { + return nullptr; + } + + path = chars.utf8(); + } + + AVFormatContext * context = nullptr; + int result = avformat_open_input(&context, path.c_str(), nullptr, nullptr); + + if (result < 0) { + ffmpeg::ThrowIOException(env, "Opening " + path + " failed: " + ffmpeg::ErrorText(result)); + return nullptr; + } + + // Per stream: its type (0 video, 1 audio, 2 other), whether its first + // packet is a key frame (1) or not (0), its first and last + // presentation time in microseconds, and its number of packets. + std::vector values(context->nb_streams * kValues, 0); + AVPacket * packet = av_packet_alloc(); + + for (unsigned i = 0; i < context->nb_streams; i++) { + const AVMediaType type = context->streams[i]->codecpar->codec_type; + + values[i * kValues] = type == AVMEDIA_TYPE_VIDEO ? 0 : type == AVMEDIA_TYPE_AUDIO ? 1 : 2; + } + + while (packet != nullptr && av_read_frame(context, packet) >= 0) { + const unsigned index = static_cast(packet->stream_index); + + if (index < context->nb_streams && packet->pts != AV_NOPTS_VALUE) { + const int64_t pts = av_rescale_q(packet->pts, context->streams[index]->time_base, + AVRational{ 1, 1000000 }); + jlong * stream = values.data() + index * kValues; + + if (stream[4] == 0) { + stream[1] = (packet->flags & AV_PKT_FLAG_KEY) != 0 ? 1 : 0; + stream[2] = pts; + stream[3] = pts; + } + + stream[3] = std::max(stream[3], pts); + stream[4]++; + } + + av_packet_unref(packet); + } + + av_packet_free(&packet); + avformat_close_input(&context); + + const jsize size = static_cast(values.size()); + jlongArray array = env->NewLongArray(size); + + if (array != nullptr) { + env->SetLongArrayRegion(array, 0, size, values.data()); + } + + return array; + }); +} diff --git a/webrtc-media/src/main/cpp/src/JNI_WriteFault.cpp b/webrtc-media/src/main/cpp/src/JNI_WriteFault.cpp index 3556bdffe..6febe8d69 100644 --- a/webrtc-media/src/main/cpp/src/JNI_WriteFault.cpp +++ b/webrtc-media/src/main/cpp/src/JNI_WriteFault.cpp @@ -36,9 +36,9 @@ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_media_recorder_WriteFault_failOpen } JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_media_recorder_WriteFault_failHeader -(JNIEnv * env, jclass caller) +(JNIEnv * env, jclass caller, jint afterHeaders) { - WriteFault::Fail(WriteFault::Call::kHeader, AVERROR(ENOSPC), 0); + WriteFault::Fail(WriteFault::Call::kHeader, AVERROR(ENOSPC), afterHeaders); } JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_media_recorder_WriteFault_failPacket diff --git a/webrtc-media/src/main/cpp/src/media/JavaRecorderObserver.cpp b/webrtc-media/src/main/cpp/src/media/JavaRecorderObserver.cpp index 459a5a14f..be8094459 100644 --- a/webrtc-media/src/main/cpp/src/media/JavaRecorderObserver.cpp +++ b/webrtc-media/src/main/cpp/src/media/JavaRecorderObserver.cpp @@ -41,6 +41,8 @@ namespace ffmpeg on_warning_ = env->GetMethodID(cls, "onNativeWarning", "(Ljava/lang/String;)V"); on_error_ = env->GetMethodID(cls, "onNativeError", "(Ljava/lang/String;)V"); on_key_frame_needed_ = env->GetMethodID(cls, "onNativeKeyFrameNeeded", "(I)V"); + on_segment_finished_ = env->GetMethodID(cls, "onNativeSegmentFinished", "(JLjava/lang/String;JJI)V"); + on_replay_saved_ = env->GetMethodID(cls, "onNativeReplaySaved", "(IIJJLjava/lang/String;)V"); env->DeleteLocalRef(cls); @@ -111,6 +113,59 @@ namespace ffmpeg Detach(attached); } + void JavaRecorderObserver::OnSegmentFinished(int64_t index, const std::string & path, + int64_t start_us, int64_t duration_us, int result) + { + if (on_segment_finished_ == nullptr) { + return; + } + + bool attached = false; + JNIEnv * env = Attach(&attached); + + if (CanCallJava(env)) { + jstring jPath = NewJavaString(env, path); + + if (jPath != nullptr) { + env->CallVoidMethod(recorder_, on_segment_finished_, static_cast(index), jPath, + static_cast(start_us), static_cast(duration_us), static_cast(result)); + env->DeleteLocalRef(jPath); + } + + ClearPendingException(env); + } + + Detach(attached); + } + + void JavaRecorderObserver::OnReplaySaved(int id, int result, int64_t start_us, + int64_t duration_us, const std::string & error) + { + if (on_replay_saved_ == nullptr) { + return; + } + + bool attached = false; + JNIEnv * env = Attach(&attached); + + if (CanCallJava(env)) { + // No text for no error. + jstring jError = error.empty() ? nullptr : NewJavaString(env, error); + + if (error.empty() || jError != nullptr) { + env->CallVoidMethod(recorder_, on_replay_saved_, static_cast(id), static_cast(result), + static_cast(start_us), static_cast(duration_us), jError); + } + if (jError != nullptr) { + env->DeleteLocalRef(jError); + } + + ClearPendingException(env); + } + + Detach(attached); + } + void JavaRecorderObserver::CallWithMessage(jmethodID method, const std::string & message) { if (method == nullptr) { diff --git a/webrtc-media/src/main/cpp/src/media/MediaRecorder.cpp b/webrtc-media/src/main/cpp/src/media/MediaRecorder.cpp index b0afe75cd..832754f15 100644 --- a/webrtc-media/src/main/cpp/src/media/MediaRecorder.cpp +++ b/webrtc-media/src/main/cpp/src/media/MediaRecorder.cpp @@ -23,13 +23,10 @@ #include #include #include +#include #include #include -extern "C" { -#include -} - namespace ffmpeg { namespace @@ -55,30 +52,63 @@ namespace ffmpeg // the header timeout and for key frame requests it held back. constexpr std::chrono::milliseconds kWriterTick(250); - bool IsMp4(const AVOutputFormat * format) + // How long the segment before takes the frames of a video track that + // has not reached a key frame in the next one, before the track waits + // for it with nothing recorded. + constexpr int64_t kDrainUs = 3000000; + + // How long a segment that is due to end waits for a key frame of a + // video track before it ends at whatever frame comes. + constexpr int64_t kRotationWaitUs = 3000000; + + // How many existing files a segment skips before it gives up. + constexpr int kMaxSkippedSegments = 1000; + + // How often a replay buffer asks for key frames, which is how far + // beyond its window it may have to reach back: a third of the window, + // but neither often enough to cost a call much, nor so rarely that the + // buffer holds much more than asked. + constexpr int64_t kMinReplayKeyFrameIntervalUs = 2000000; + constexpr int64_t kMaxReplayKeyFrameIntervalUs = 10000000; + + std::string SegmentPattern(const MediaRecorder::SegmentConfig & segments) { - return std::strcmp(format->name, "mp4") == 0 || std::strcmp(format->name, "mov") == 0; + return segments.prefix + "%0" + std::to_string(segments.width) + "d" + segments.suffix; } } - MediaRecorder::MediaRecorder(const webrtc_java_api * api, std::string path) : + MediaRecorder::MediaRecorder(const webrtc_java_api * api, Mode mode, std::string path) : api_(api), + mode_(mode), path_(std::move(path)), - out_of_memory_error_("Recording to " + path_ + " failed: " + ErrorText(AVERROR(ENOMEM))) + subject_(mode == Mode::kReplay ? "Buffering for replays" : "Recording to " + path_), + out_of_memory_error_(subject_ + " failed: " + ErrorText(AVERROR(ENOMEM))) { } - MediaRecorder::~MediaRecorder() + MediaRecorder::MediaRecorder(const webrtc_java_api * api, std::string path) : + MediaRecorder(api, Mode::kFile, std::move(path)) { - Stop(); + } - if (context_ != nullptr) { - if (context_->pb != nullptr && !(context_->oformat->flags & AVFMT_NOFILE)) { - avio_closep(&context_->pb); - } + MediaRecorder::MediaRecorder(const webrtc_java_api * api, SegmentConfig segments) : + MediaRecorder(api, Mode::kSegments, SegmentPattern(segments)) + { + segments_ = std::move(segments); + next_index_ = segments_.first_index; + } - avformat_free_context(context_); - } + MediaRecorder::MediaRecorder(const webrtc_java_api * api, ReplayConfig replay) : + MediaRecorder(api, Mode::kReplay, std::string()) + { + replay_ = replay; + key_frame_interval_us_ = std::min(std::max(replay_.window_us / 3, kMinReplayKeyFrameIntervalUs), + kMaxReplayKeyFrameIntervalUs); + } + + MediaRecorder::~MediaRecorder() + { + Stop(); } void MediaRecorder::SetObserver(std::unique_ptr observer) @@ -88,28 +118,29 @@ namespace ffmpeg int MediaRecorder::Open() { - // The container follows the file name; a name FFmpeg cannot place - // gets Matroska, which holds every codec WebRTC sends. - int result = avformat_alloc_output_context2(&context_, nullptr, nullptr, path_.c_str()); - - if (result < 0 || context_ == nullptr) { - result = avformat_alloc_output_context2(&context_, nullptr, "matroska", path_.c_str()); - } - if (result < 0) { - return result; - } + if (mode_ == Mode::kFile) { + output_ = std::make_unique(path_, 0, 0); - // Frames arrive in real time, so the streams never drift far apart, - // and holding back more for interleaving only costs memory. - context_->max_interleave_delta = 2000000; - - if (!(context_->oformat->flags & AVFMT_NOFILE)) { - result = WriteFault::Check(WriteFault::Call::kOpen, - avio_open(&context_->pb, path_.c_str(), AVIO_FLAG_WRITE)); + int result = output_->Open(false); if (result < 0) { return result; } + + format_ = output_->GetFormat(); + } + else if (mode_ == Mode::kSegments) { + // As a segment will choose it when it opens. + const std::string name = "segment" + segments_.suffix; + + format_ = av_guess_format(nullptr, name.c_str(), nullptr); + + if (format_ == nullptr) { + format_ = av_guess_format("matroska", nullptr, nullptr); + } + if (format_ == nullptr) { + return AVERROR_MUXER_NOT_FOUND; + } } return 0; @@ -171,6 +202,14 @@ namespace ffmpeg // before there is a writer, which would finish the file on its way // out, so that taking the observers off again undoes all of it. try { + const size_t count = tracks_.size(); + + switched_.assign(count, true); + awaiting_segment_.assign(count, false); + key_times_.resize(count); + last_key_us_.assign(count, 0); + last_frame_us_.assign(count, std::numeric_limits::min()); + // The inputs do not change once started, so the callbacks may hold // on to them without the lock. for (const auto & input : inputs_) { @@ -288,6 +327,25 @@ namespace ffmpeg return stats; } + bool MediaRecorder::SaveReplay(int id, std::string path) + { + std::lock_guard lock(mutex_); + + if (mode_ != Mode::kReplay || !started_ || stopped_ || writer_ended_) { + return false; + } + + SaveRequest request; + request.id = id; + request.path = std::move(path); + + save_requests_.push_back(std::move(request)); + poke_ = true; + wake_.notify_one(); + + return true; + } + void MediaRecorder::RemoveObservers() { for (const auto & input : inputs_) { @@ -358,7 +416,8 @@ namespace ffmpeg input->ssrc = frame->ssrc; } - if (frame->mime_type == nullptr || input->mime_type != frame->mime_type) { + if (frame->mime_type == nullptr + || (mode_ == Mode::kFile && input->mime_type != frame->mime_type)) { // A stream in a file cannot change its codec halfway. if (!input->reported_codec_change) { input->reported_codec_change = true; @@ -372,6 +431,16 @@ namespace ffmpeg return; } + if (input->mime_type != frame->mime_type) { + // Segments and replays go on with the new codec, which the writer + // describes anew, from a key frame. + input->mime_type = frame->mime_type; + + if (video) { + input->waiting_for_key_frame = true; + } + } + if (video && input->waiting_for_key_frame) { if (!frame->key_frame) { input->stats.dropped_awaiting_key_frame++; @@ -498,6 +567,7 @@ namespace ffmpeg std::deque batch; std::vector warnings; std::vector key_frame_requests; + std::vector saves; std::unique_lock lock(mutex_); @@ -511,6 +581,7 @@ namespace ffmpeg batch.swap(queue_); queued_bytes_ = 0; warnings.swap(pending_warnings_); + saves.swap(save_requests_); CollectKeyFrameRequestsLocked(&key_frame_requests, api_->now_us()); @@ -537,17 +608,37 @@ namespace ffmpeg Handle(std::move(frame)); } - // Nothing may arrive for a track that is waited for, so the - // clock is looked at here as well. - MaybeWriteHeader(false); + const int64_t now_us = api_->now_us(); + + if (mode_ == Mode::kReplay) { + // After the frames that came before the request. + for (const SaveRequest & save : saves) { + Save(save); + } + + saves.clear(); + + RequestReplayKeyFrames(now_us); + } + else { + // Nothing may arrive for a track that is waited for, so the + // clock is looked at here as well. + MaybeWriteHeader(false); + + if (mode_ == Mode::kSegments) { + CheckSegments(now_us); + } + } lock.lock(); - if (stopping && queue_.empty()) { + if (stopping && queue_.empty() && save_requests_.empty()) { break; } } + writer_ended_ = true; + lock.unlock(); Finish(); @@ -565,9 +656,15 @@ namespace ffmpeg RecorderTrack & track = *tracks_[frame.track]; + if (track.GetStatus() == RecorderTrack::Status::kReady && frame.mime_type != track.GetMimeType()) { + // Only segments and replays get here: the frames of a single file + // keep the codec they began with. + ChangeCodec(track, frame); + } + if (track.GetStatus() == RecorderTrack::Status::kPending) { std::string message; - RecorderTrack::Status status = track.Probe(frame, context_->oformat, &message); + RecorderTrack::Status status = track.Probe(frame, format_, &message); if (status == RecorderTrack::Status::kUnsupported) { Warn(message); @@ -584,12 +681,24 @@ namespace ffmpeg if (first_ready_us_ == 0) { first_ready_us_ = api_->now_us(); } + if (awaiting_segment_[frame.track] && !rotation_due_) { + // Described with its new codec, which goes into a segment of + // its own. + DueRotation(); + } } if (track.GetStatus() != RecorderTrack::Status::kReady) { return; } + track.Timestamp(frame, start_us_); + + if (mode_ == Mode::kReplay) { + Buffer(std::move(frame)); + return; + } + if (!header_written_) { pending_bytes_ += static_cast(frame.packet->size); pending_.push_back(std::move(frame)); @@ -598,21 +707,609 @@ namespace ffmpeg return; } + Route(frame); + } + + void MediaRecorder::ChangeCodec(RecorderTrack & track, const RecordedFrame & frame) + { + const int index = track.GetIndex(); + + Warn("Track " + std::to_string(index) + " changed its codec from " + track.GetMimeType() + + " to " + frame.mime_type + + (mode_ == Mode::kSegments ? ", and goes on in the next segment" : "")); + + track.Reset(); + + if (mode_ == Mode::kReplay) { + // A stream in a file cannot change its codec, and a replay holds + // the new one. + RemoveFromBuffer(index); + } + else if (!header_written_) { + pending_.erase(std::remove_if(pending_.begin(), pending_.end(), + [this, index](const RecordedFrame & pending) { + if (pending.track != index) { + return false; + } + + pending_bytes_ -= static_cast(pending.packet->size); + return true; + }), pending_.end()); + } + else { + awaiting_segment_[index] = true; + } + } + + void MediaRecorder::Route(RecordedFrame & frame) + { + if (mode_ == Mode::kSegments) { + RouteSegment(frame); + } // A track that got ready only after the header has no stream. - if (track.GetStream() != nullptr) { - Write(frame); + else if (output_->HasStream(frame.track)) { + Write(*output_, frame); } } - void MediaRecorder::Write(RecordedFrame & frame) + void MediaRecorder::RouteSegment(RecordedFrame & frame) { - AVPacket * packet = tracks_[frame.track]->Stamp(frame, start_us_); + const int index = frame.track; + const bool video = tracks_[index]->IsVideo(); + + if (rotation_due_) { + // A segment begins with a key frame of a video track. With no + // video, or none that sends one in time, it begins anywhere. + if ((video && frame.key_frame) || !AnyVideoReady() + || api_->now_us() - rotation_due_us_ > kRotationWaitUs) { + Rotate(frame); + + if (failed_) { + return; + } + } + } + + if (awaiting_segment_[index]) { + return; + } + + if (video && !switched_[index]) { + // Until its own key frame, a video track goes on in the segment + // before, so that both play without a gap. + if (frame.key_frame && output_->HasStream(index)) { + switched_[index] = true; + + Write(*output_, frame); - // Takes the packet's reference and leaves the packet blank. - int result = WriteFault::Check(WriteFault::Call::kPacket, av_interleaved_write_frame(context_, packet)); + if (draining_ != nullptr && !Draining()) { + FinishSegment(std::move(draining_)); + } + } + else if (draining_ != nullptr && draining_->HasStream(index)) { + Write(*draining_, frame); + } + else if (output_->HasStream(index)) { + CountAwaitingKeyFrame(index); + } + } + else if (output_->HasStream(index)) { + Write(*output_, frame); + } + + if (!failed_ && !rotation_due_ && SegmentLimitReached()) { + DueRotation(); + } + } + + void MediaRecorder::Rotate(const RecordedFrame & frame) + { + // A segment that still drains when the next one is due is done. + FinishSegment(std::move(draining_)); + + if (failed_) { + return; + } + + draining_ = std::move(output_); + + if (!OpenSegment(frame.timeline_us)) { + FinishSegment(std::move(draining_)); + return; + } + + for (size_t i = 0; i < tracks_.size(); i++) { + switched_[i] = !tracks_[i]->IsVideo() + || (static_cast(i) == frame.track && frame.key_frame); + + // A track that changed its codec and is not described anew yet + // waits for the segment after. + awaiting_segment_[i] = awaiting_segment_[i] && !output_->HasStream(static_cast(i)); + } + + rotation_due_ = false; + drain_started_us_ = api_->now_us(); + + if (!Draining()) { + FinishSegment(std::move(draining_)); + } + } + + void MediaRecorder::DueRotation() + { + rotation_due_ = true; + rotation_due_us_ = api_->now_us(); + + RequestKeyFrames(); + } + + bool MediaRecorder::OpenSegment(int64_t start_us) + { + for (int skipped = 0; ; skipped++) { + const int64_t index = next_index_++; + auto segment = std::make_unique(SegmentPath(index), start_us, index); + const std::string & path = segment->GetPath(); + + int result = segment->Open(true); + + if (result == AVERROR(EEXIST) && skipped < kMaxSkippedSegments) { + // Left as it is; reported once, not for every file in a row. + if (!skipped_existing_) { + skipped_existing_ = true; + Warn(path + " exists already, so the segment goes into the next free file"); + } + continue; + } + if (result < 0) { + // Nothing to delete: the file was not opened, or is not ours. + Fail("Opening " + path + " failed", result); + return false; + } + + for (const auto & track : tracks_) { + if (track->GetStatus() == RecorderTrack::Status::kReady) { + result = segment->AddStream(*track); + + if (result < 0) { + Fail("Adding track " + std::to_string(track->GetIndex()) + " to " + path + " failed", result); + break; + } + } + } + + if (result >= 0) { + result = segment->WriteHeader(); + + if (result < 0) { + Fail("Writing the header of " + path + " failed", result); + } + } + + if (result < 0) { + // Closed first, since a file that is open cannot be deleted + // everywhere. Its failure is the one reported. + segment->Close(); + + if (observer_ != nullptr) { + observer_->OnSegmentFinished(index, path, start_us, 0, + static_cast(Result::kFailed)); + } + return false; + } + + output_ = std::move(segment); + + return true; + } + } + + void MediaRecorder::FinishSegment(std::unique_ptr segment) + { + if (segment == nullptr) { + return; + } + + // Even after a failed write: whatever made it into the file is only + // playable with a trailer. After an earlier failure, the same cause + // is not reported twice. + int result = segment->WriteTrailer(); if (result < 0) { - Fail("Writing to " + path_ + " failed", result); + if (!failed_) { + Fail("Finishing " + segment->GetPath() + " failed", result); + } + segment->SetFailed(); + } + + result = segment->Close(); + + if (result < 0) { + if (!failed_) { + Fail("Closing " + segment->GetPath() + " failed", result); + } + segment->SetFailed(); + } + + Result outcome = Result::kFailed; + + if (segment->HasMedia()) { + outcome = segment->IsFailed() ? Result::kPartial : Result::kComplete; + } + + if (observer_ != nullptr) { + observer_->OnSegmentFinished(segment->GetIndex(), segment->GetPath(), + segment->GetStartUs(), segment->GetDurationUs(), static_cast(outcome)); + } + } + + void MediaRecorder::CheckSegments(int64_t now_us) + { + if (failed_ || output_ == nullptr) { + return; + } + + // A video track that sends no key frame in time waits for it with + // nothing recorded, rather than hold the segment before open. + if (draining_ != nullptr && now_us - drain_started_us_ > kDrainUs) { + FinishSegment(std::move(draining_)); + + if (failed_) { + return; + } + } + + std::lock_guard lock(mutex_); + + for (size_t i = 0; i < tracks_.size(); i++) { + const RecorderTrack & track = *tracks_[i]; + + if (track.GetStatus() != RecorderTrack::Status::kReady || !track.IsVideo()) { + continue; + } + + // Asked again as long as they are waited for; the requests go out + // no more than once a second. + if (rotation_due_ || (!switched_[i] && output_->HasStream(static_cast(i)))) { + WantKeyFrameLocked(inputs_[i].get()); + } + } + } + + bool MediaRecorder::Draining() const + { + for (size_t i = 0; i < tracks_.size(); i++) { + if (!switched_[i] && !awaiting_segment_[i] && draining_->HasStream(static_cast(i))) { + return true; + } + } + + return false; + } + + std::string MediaRecorder::SegmentPath(int64_t index) const + { + std::string digits = std::to_string(index); + + if (digits.size() < static_cast(segments_.width)) { + digits.insert(0, static_cast(segments_.width) - digits.size(), '0'); + } + + return segments_.prefix + digits + segments_.suffix; + } + + void MediaRecorder::RequestKeyFrames() + { + std::lock_guard lock(mutex_); + + for (size_t i = 0; i < tracks_.size(); i++) { + const RecorderTrack & track = *tracks_[i]; + + if (track.GetStatus() == RecorderTrack::Status::kReady && track.IsVideo()) { + WantKeyFrameLocked(inputs_[i].get()); + } + } + } + + void MediaRecorder::CountAwaitingKeyFrame(int track) + { + std::lock_guard lock(mutex_); + + inputs_[track]->stats.dropped_awaiting_key_frame++; + } + + bool MediaRecorder::AnyVideoReady() const + { + for (const auto & track : tracks_) { + if (track->GetStatus() == RecorderTrack::Status::kReady && track->IsVideo()) { + return true; + } + } + + return false; + } + + bool MediaRecorder::SegmentLimitReached() const + { + if (segments_.max_duration_us > 0 && output_->GetDurationUs() >= segments_.max_duration_us) { + return true; + } + + return segments_.max_bytes > 0 && output_->GetBytes() >= segments_.max_bytes; + } + + void MediaRecorder::Buffer(RecordedFrame frame) + { + const int index = frame.track; + + if (tracks_[index]->IsVideo() && frame.key_frame) { + key_times_[index].push_back(frame.timeline_us); + last_key_us_[index] = api_->now_us(); + } + + last_frame_us_[index] = frame.timeline_us; + ring_bytes_ += static_cast(frame.packet->size); + ring_.push_back(std::move(frame)); + + if (!header_written_) { + header_written_ = true; + + if (observer_ != nullptr) { + observer_->OnStarted(); + } + } + + TrimBuffer(); + } + + void MediaRecorder::TrimBuffer() + { + const int64_t cutoff = ring_.back().timeline_us - replay_.window_us; + int64_t keep_from = cutoff; + + // Every video track that still sends needs the key frame its part of + // the window decodes from: the last one before the window, or the + // first one in it. + for (size_t i = 0; i < tracks_.size(); i++) { + const std::deque & keys = key_times_[i]; + + if (keys.empty() || last_frame_us_[i] < cutoff) { + continue; + } + + int64_t from = keys.front(); + + for (int64_t key : keys) { + if (key > cutoff) { + break; + } + from = key; + } + + keep_from = std::min(keep_from, from); + } + + // Past its limit, the buffer lets go of the oldest frames whatever + // they are; a replay then begins at the next key frame. + while (!ring_.empty() && (ring_.front().timeline_us < keep_from + || ring_bytes_ > static_cast(replay_.max_bytes))) { + const RecordedFrame & front = ring_.front(); + const int index = front.track; + + if (front.key_frame && tracks_[index]->IsVideo() && !key_times_[index].empty()) { + key_times_[index].pop_front(); + + // What follows of the track decodes from nothing, so it waits + // for the next key frame, and asks for it. + if (key_times_[index].empty()) { + RestartAtKeyFrame(index); + } + } + + ring_bytes_ -= static_cast(front.packet->size); + ring_.pop_front(); + } + } + + void MediaRecorder::RemoveFromBuffer(int track) + { + ring_.erase(std::remove_if(ring_.begin(), ring_.end(), + [this, track](const RecordedFrame & frame) { + if (frame.track != track) { + return false; + } + + ring_bytes_ -= static_cast(frame.packet->size); + return true; + }), ring_.end()); + + key_times_[track].clear(); + last_frame_us_[track] = std::numeric_limits::min(); + } + + void MediaRecorder::RequestReplayKeyFrames(int64_t now_us) + { + if (failed_) { + return; + } + + std::lock_guard lock(mutex_); + + for (size_t i = 0; i < tracks_.size(); i++) { + const RecorderTrack & track = *tracks_[i]; + + // WebRTC sends key frames rarely of its own accord, and without + // them the buffer could let go of nothing. + if (track.GetStatus() == RecorderTrack::Status::kReady && track.IsVideo() + && now_us - last_key_us_[i] >= key_frame_interval_us_) { + WantKeyFrameLocked(inputs_[i].get()); + } + } + } + + void MediaRecorder::Save(const SaveRequest & request) + { + if (observer_ == nullptr) { + return; + } + if (ring_.empty()) { + observer_->OnReplaySaved(request.id, static_cast(Result::kEmpty), 0, 0, std::string()); + return; + } + + const size_t count = tracks_.size(); + const int64_t cutoff = ring_.back().timeline_us - replay_.window_us; + const int64_t none = std::numeric_limits::max(); + + // Where each track begins: a video track at the key frame its part of + // the window decodes from, the others where the earliest of those is. + std::vector begin(count, none); + int64_t start = none; + + for (size_t i = 0; i < count; i++) { + const std::deque & keys = key_times_[i]; + + if (!tracks_[i]->IsVideo() || keys.empty() || last_frame_us_[i] < cutoff) { + continue; + } + + int64_t from = keys.front(); + + for (int64_t key : keys) { + if (key > cutoff) { + break; + } + from = key; + } + + begin[i] = from; + start = std::min(start, from); + } + + if (start == none) { + start = std::max(cutoff, ring_.front().timeline_us); + } + + for (size_t i = 0; i < count; i++) { + if (!tracks_[i]->IsVideo()) { + begin[i] = start; + } + } + + std::vector has_frames(count, false); + + for (const RecordedFrame & frame : ring_) { + if (frame.timeline_us >= begin[frame.track]) { + has_frames[frame.track] = true; + } + } + + RecorderOutput output(request.path, start, request.id); + const std::string & path = output.GetPath(); + + int result = output.Open(false); + + if (result < 0) { + SaveFailed(request, "Opening " + path + " failed", result); + return; + } + + for (size_t i = 0; i < count; i++) { + std::string message; + + if (!has_frames[i] || tracks_[i]->GetStatus() != RecorderTrack::Status::kReady) { + continue; + } + if (!tracks_[i]->CanBeHeldBy(output.GetFormat(), &message)) { + Warn(message); + continue; + } + + result = output.AddStream(*tracks_[i]); + + if (result < 0) { + output.Close(); + SaveFailed(request, "Adding track " + std::to_string(i) + " to " + path + " failed", result); + return; + } + } + + if (!output.HasStreams()) { + output.Close(); + observer_->OnReplaySaved(request.id, static_cast(Result::kEmpty), 0, 0, std::string()); + return; + } + + result = output.WriteHeader(); + + if (result < 0) { + output.Close(); + SaveFailed(request, "Writing the header of " + path + " failed", result); + return; + } + + std::vector begun(count, false); + std::string error; + + for (RecordedFrame & frame : ring_) { + const int index = frame.track; + + if (!output.HasStream(index) || frame.timeline_us < begin[index]) { + continue; + } + if (tracks_[index]->IsVideo() && !begun[index]) { + if (!frame.key_frame) { + continue; + } + begun[index] = true; + } + + // The buffer keeps the frame for the replays to come. + result = output.Write(frame, true); + + if (result < 0) { + error = "Writing to " + path + " failed: " + ErrorText(result); + break; + } + } + + // Even after a failed write: whatever made it into the file is only + // playable with a trailer. + result = output.WriteTrailer(); + + if (result < 0 && error.empty()) { + error = "Finishing " + path + " failed: " + ErrorText(result); + } + + result = output.Close(); + + if (result < 0 && error.empty()) { + error = "Closing " + path + " failed: " + ErrorText(result); + } + + Result outcome; + + if (output.HasMedia()) { + outcome = error.empty() ? Result::kComplete : Result::kPartial; + } + else { + outcome = error.empty() ? Result::kEmpty : Result::kFailed; + } + + observer_->OnReplaySaved(request.id, static_cast(outcome), start, output.GetDurationUs(), error); + } + + void MediaRecorder::SaveFailed(const SaveRequest & request, const std::string & message, int error) + { + observer_->OnReplaySaved(request.id, static_cast(Result::kFailed), 0, 0, + message + ": " + ErrorText(error)); + } + + void MediaRecorder::Write(RecorderOutput & output, RecordedFrame & frame) + { + int result = output.Write(frame, false); + + if (result < 0) { + Fail("Writing to " + output.GetPath() + " failed", result, &output); } } @@ -640,40 +1337,47 @@ namespace ffmpeg } for (const auto & track : tracks_) { - if (track->GetStatus() == RecorderTrack::Status::kReady) { - int result = track->CreateStream(context_); - - if (result < 0) { - Fail("Adding track " + std::to_string(track->GetIndex()) + " to the file failed", result); - pending_.clear(); - return false; - } - } - else if (track->GetStatus() == RecorderTrack::Status::kPending) { + if (track->GetStatus() == RecorderTrack::Status::kPending) { Warn("Track " + std::to_string(track->GetIndex()) - + " had no media to record when the recording began, and is left out"); + + " had no media to record when the recording began, and is left out" + + (mode_ == Mode::kSegments ? " until the next segment" : "")); } } - AVDictionary * options = nullptr; + if (mode_ == Mode::kSegments) { + // The first segment begins with the earliest frame held back, + // which is a key frame for every video track. + int64_t start = std::numeric_limits::max(); - if (IsMp4(context_->oformat)) { - // Fragmented, so that a recording cut short, by a crash or a full - // disk, still plays up to where it stopped; and in fragments of a - // second rather than per key frame, which WebRTC sends rarely and - // which would hold whole minutes in memory. - av_dict_set(&options, "movflags", "+empty_moov+default_base_moof", 0); - av_dict_set(&options, "frag_duration", "1000000", 0); - } + for (const RecordedFrame & frame : pending_) { + start = std::min(start, frame.timeline_us); + } - int result = WriteFault::Check(WriteFault::Call::kHeader, avformat_write_header(context_, &options)); + if (!OpenSegment(start)) { + pending_.clear(); + return false; + } + } + else { + for (const auto & track : tracks_) { + if (track->GetStatus() == RecorderTrack::Status::kReady) { + int result = output_->AddStream(*track); + + if (result < 0) { + Fail("Adding track " + std::to_string(track->GetIndex()) + " to the file failed", result); + pending_.clear(); + return false; + } + } + } - av_dict_free(&options); + int result = output_->WriteHeader(); - if (result < 0) { - Fail("Writing the header of " + path_ + " failed", result); - pending_.clear(); - return false; + if (result < 0) { + Fail("Writing the header of " + path_ + " failed", result); + pending_.clear(); + return false; + } } header_written_ = true; @@ -686,7 +1390,7 @@ namespace ffmpeg RecordedFrame frame = std::move(pending_.front()); pending_.pop_front(); - Write(frame); + Route(frame); } pending_.clear(); @@ -697,32 +1401,42 @@ namespace ffmpeg void MediaRecorder::Finish() { + if (mode_ == Mode::kReplay) { + ring_.clear(); + ring_bytes_ = 0; + return; + } + MaybeWriteHeader(true); + pending_.clear(); + + if (mode_ == Mode::kSegments) { + FinishSegment(std::move(draining_)); + FinishSegment(std::move(output_)); + return; + } + if (header_written_) { // Even after a failed write: whatever made it into the file // is only playable with a trailer. - int result = WriteFault::Check(WriteFault::Call::kTrailer, av_write_trailer(context_)); + int result = output_->WriteTrailer(); if (result < 0 && !failed_) { Fail("Finishing " + path_ + " failed", result); } } - pending_.clear(); - Close(); } void MediaRecorder::Close() { - if (context_ == nullptr || context_->pb == nullptr || (context_->oformat->flags & AVFMT_NOFILE)) { + if (output_ == nullptr) { return; } - // Flushes what is still buffered, so a full disk may only show here, - // and the file system may refuse to close a file it could not keep. - int result = WriteFault::Check(WriteFault::Call::kClose, avio_closep(&context_->pb)); + int result = output_->Close(); // After an earlier failure, the same cause is not reported twice. if (result < 0 && !failed_) { @@ -730,10 +1444,14 @@ namespace ffmpeg } } - void MediaRecorder::Fail(const std::string & message, int error) + void MediaRecorder::Fail(const std::string & message, int error, RecorderOutput * output) { failed_ = true; + if (output != nullptr) { + output->SetFailed(); + } + { std::lock_guard lock(mutex_); @@ -756,13 +1474,16 @@ namespace ffmpeg failed_ = true; std::deque dropped; + std::vector saves; try { std::lock_guard lock(mutex_); accepting_ = false; + writer_ended_ = true; queue_.swap(dropped); queued_bytes_ = 0; + save_requests_.swap(saves); } catch (...) { // Without the lock the callbacks go on queueing, up to the limit, @@ -772,6 +1493,8 @@ namespace ffmpeg dropped.clear(); pending_.clear(); pending_bytes_ = 0; + ring_.clear(); + ring_bytes_ = 0; const std::string * message = &out_of_memory_error_; std::string described; @@ -783,7 +1506,7 @@ namespace ffmpeg } catch (const std::exception & e) { try { - described = "Recording to " + path_ + " failed: " + e.what(); + described = subject_ + " failed: " + e.what(); message = &described; } catch (...) { @@ -791,7 +1514,7 @@ namespace ffmpeg } catch (...) { try { - described = "Recording to " + path_ + " failed"; + described = subject_ + " failed"; message = &described; } catch (...) { @@ -806,6 +1529,18 @@ namespace ffmpeg catch (...) { } + // Replays asked for and not saved are answered, so that nobody waits + // for them until the stop. + for (const SaveRequest & save : saves) { + try { + if (observer_ != nullptr) { + observer_->OnReplaySaved(save.id, static_cast(Result::kFailed), 0, 0, *message); + } + } + catch (...) { + } + } + // Once failed, finishing writes no more media and reports nothing, // so it needs no memory: the trailer keeps what is in the file // playable. Should it throw all the same, Stop() still closes the diff --git a/webrtc-media/src/main/cpp/src/media/RecorderOutput.cpp b/webrtc-media/src/main/cpp/src/media/RecorderOutput.cpp new file mode 100644 index 000000000..2d77eddfa --- /dev/null +++ b/webrtc-media/src/main/cpp/src/media/RecorderOutput.cpp @@ -0,0 +1,278 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#include "media/RecorderOutput.h" +#include "media/WriteFault.h" + +#include +#include +#include +#include + +extern "C" { +#include +#include +} + +namespace ffmpeg +{ + namespace + { + bool IsMp4(const AVOutputFormat * format) + { + return std::strcmp(format->name, "mp4") == 0 || std::strcmp(format->name, "mov") == 0; + } + } + + RecorderOutput::RecorderOutput(std::string path, int64_t start_us, int64_t index) : + path_(std::move(path)), + start_us_(start_us), + index_(index) + { + } + + RecorderOutput::~RecorderOutput() + { + if (context_ != nullptr) { + if (context_->pb != nullptr && !(context_->oformat->flags & AVFMT_NOFILE)) { + avio_closep(&context_->pb); + } + + avformat_free_context(context_); + } + } + + int RecorderOutput::Open(bool exclusive) + { + int result = avformat_alloc_output_context2(&context_, nullptr, nullptr, path_.c_str()); + + if (result < 0 || context_ == nullptr) { + result = avformat_alloc_output_context2(&context_, nullptr, "matroska", path_.c_str()); + } + if (result < 0) { + return result; + } + + // Frames arrive in real time, so the streams never drift far apart, + // and holding back more for interleaving only costs memory. + context_->max_interleave_delta = 2000000; + + if (context_->oformat->flags & AVFMT_NOFILE) { + return 0; + } + + // FFmpeg opens a file for writing by emptying it, so a file that + // exists is looked for first. Something else creating it in between + // is not guarded against. + if (exclusive && avio_check(path_.c_str(), 0) >= 0) { + return AVERROR(EEXIST); + } + + return WriteFault::Check(WriteFault::Call::kOpen, + avio_open(&context_->pb, path_.c_str(), AVIO_FLAG_WRITE)); + } + + const std::string & RecorderOutput::GetPath() const + { + return path_; + } + + int64_t RecorderOutput::GetIndex() const + { + return index_; + } + + int64_t RecorderOutput::GetStartUs() const + { + return start_us_; + } + + const AVOutputFormat * RecorderOutput::GetFormat() const + { + return context_ != nullptr ? context_->oformat : nullptr; + } + + int RecorderOutput::AddStream(const RecorderTrack & track) + { + const size_t index = static_cast(track.GetIndex()); + + if (streams_.size() <= index) { + streams_.resize(index + 1); + } + + Stream & stream = streams_[index]; + int result = track.CreateStream(context_, &stream.stream); + + if (result < 0) { + stream.stream = nullptr; + return result; + } + + stream.clock_rate = track.GetClockRate(); + + return 0; + } + + bool RecorderOutput::HasStream(int track) const + { + return track >= 0 && static_cast(track) < streams_.size() + && streams_[track].stream != nullptr; + } + + bool RecorderOutput::HasStreams() const + { + return std::any_of(streams_.begin(), streams_.end(), + [](const Stream & stream) { return stream.stream != nullptr; }); + } + + int RecorderOutput::WriteHeader() + { + AVDictionary * options = nullptr; + + if (IsMp4(context_->oformat)) { + // Fragmented, so that a recording cut short, by a crash or a full + // disk, still plays up to where it stopped; and in fragments of a + // second rather than per key frame, which WebRTC sends rarely and + // which would hold whole minutes in memory. + av_dict_set(&options, "movflags", "+empty_moov+default_base_moof", 0); + av_dict_set(&options, "frag_duration", "1000000", 0); + } + + int result = WriteFault::Check(WriteFault::Call::kHeader, avformat_write_header(context_, &options)); + + av_dict_free(&options); + + if (result < 0) { + return result; + } + + header_written_ = true; + + if (context_->pb != nullptr) { + bytes_ = avio_tell(context_->pb); + } + + return 0; + } + + bool RecorderOutput::IsHeaderWritten() const + { + return header_written_; + } + + int RecorderOutput::Write(RecordedFrame & frame, bool keep) + { + Stream & stream = streams_[frame.track]; + AVPacket * packet = frame.packet.get(); + PacketPtr reference; + + if (keep) { + // Shares the payload, which a buffer holds on to. + reference = PacketPtr(av_packet_alloc()); + + if (reference == nullptr || av_packet_ref(reference.get(), packet) < 0) { + return AVERROR(ENOMEM); + } + + packet = reference.get(); + } + + const AVRational track_time_base{ 1, stream.clock_rate }; + const int64_t start_pts = av_rescale(start_us_, stream.clock_rate, 1000000); + + // Every container wants increasing timestamps, and some want them + // strictly increasing even where frames share an RTP timestamp. A + // frame of one track that arrived a little before the frame that + // began the file is moved to its start. + int64_t pts = av_rescale_q(std::max(frame.pts - start_pts, 0), + track_time_base, stream.stream->time_base); + + if (pts <= stream.last_pts) { + pts = stream.last_pts + 1; + } + + stream.last_pts = pts; + + packet->pts = pts; + packet->dts = pts; + packet->stream_index = stream.stream->index; + packet->time_base = stream.stream->time_base; + + if (frame.key_frame || stream.stream->codecpar->codec_type == AVMEDIA_TYPE_AUDIO) { + packet->flags |= AV_PKT_FLAG_KEY; + } + + const int size = packet->size; + + // Takes the packet's reference and leaves the packet blank. + int result = WriteFault::Check(WriteFault::Call::kPacket, av_interleaved_write_frame(context_, packet)); + + if (result < 0) { + return result; + } + + packets_++; + bytes_ += size; + last_us_ = std::max(last_us_, frame.timeline_us); + + return 0; + } + + int RecorderOutput::WriteTrailer() + { + if (!header_written_) { + return 0; + } + + return WriteFault::Check(WriteFault::Call::kTrailer, av_write_trailer(context_)); + } + + int RecorderOutput::Close() + { + if (context_ == nullptr || context_->pb == nullptr || (context_->oformat->flags & AVFMT_NOFILE)) { + return 0; + } + + // Flushes what is still buffered, so a full disk may only show here, + // and the file system may refuse to close a file it could not keep. + return WriteFault::Check(WriteFault::Call::kClose, avio_closep(&context_->pb)); + } + + bool RecorderOutput::HasMedia() const + { + return packets_ > 0; + } + + int64_t RecorderOutput::GetDurationUs() const + { + return packets_ > 0 ? std::max(last_us_ - start_us_, 0) : 0; + } + + int64_t RecorderOutput::GetBytes() const + { + return bytes_; + } + + void RecorderOutput::SetFailed() + { + failed_ = true; + } + + bool RecorderOutput::IsFailed() const + { + return failed_; + } +} diff --git a/webrtc-media/src/main/cpp/src/media/RecorderTrack.cpp b/webrtc-media/src/main/cpp/src/media/RecorderTrack.cpp index f418b5ea1..edfb81d3f 100644 --- a/webrtc-media/src/main/cpp/src/media/RecorderTrack.cpp +++ b/webrtc-media/src/main/cpp/src/media/RecorderTrack.cpp @@ -263,6 +263,16 @@ namespace ffmpeg return media_type_ == AVMEDIA_TYPE_VIDEO; } + int RecorderTrack::GetClockRate() const + { + return clock_rate_; + } + + const std::string & RecorderTrack::GetMimeType() const + { + return mime_type_; + } + RecorderTrack::Status RecorderTrack::Probe(const RecordedFrame & frame, const AVOutputFormat * format, std::string * message) { @@ -280,17 +290,17 @@ namespace ffmpeg return status_; } - if (!CanHold(format, codec->codec_id)) { - *message = "Track " + std::to_string(index_) + " is " + frame.mime_type - + ", which a " + format->name + " file cannot hold; Matroska (.mkv) holds every codec WebRTC sends"; - status_ = Status::kUnsupported; - - return status_; - } + mime_type_ = frame.mime_type; media_type_ = codec->media_type; codec_id_ = codec->codec_id; clock_rate_ = codec->clock_rate; + + if (format != nullptr && !CanBeHeldBy(format, message)) { + status_ = Status::kUnsupported; + + return status_; + } } bool described = media_type_ == AVMEDIA_TYPE_VIDEO @@ -304,7 +314,36 @@ namespace ffmpeg return status_; } - int RecorderTrack::CreateStream(AVFormatContext * context) + bool RecorderTrack::CanBeHeldBy(const AVOutputFormat * format, std::string * message) const + { + if (CanHold(format, codec_id_)) { + return true; + } + + *message = "Track " + std::to_string(index_) + " is " + mime_type_ + + ", which a " + format->name + " file cannot hold; Matroska (.mkv) holds every codec WebRTC sends"; + + return false; + } + + void RecorderTrack::Reset() + { + status_ = Status::kPending; + media_type_ = AVMEDIA_TYPE_UNKNOWN; + codec_id_ = AV_CODEC_ID_NONE; + clock_rate_ = 0; + width_ = 0; + height_ = 0; + channels_ = 0; + extradata_.clear(); + mime_type_.clear(); + + // The new codec may have a clock of its own, so the track is placed + // on the timeline anew. + anchored_ = false; + } + + int RecorderTrack::CreateStream(AVFormatContext * context, AVStream ** created) const { AVStream * stream = avformat_new_stream(context, nullptr); @@ -337,24 +376,16 @@ namespace ffmpeg par->extradata_size = static_cast(extradata_.size()); } - // A hint; the muxer picks the time base it stores, which Stamp() + // A hint; the muxer picks the time base it stores, which the output // converts to. stream->time_base = AVRational{ 1, clock_rate_ }; - stream_ = stream; + *created = stream; return 0; } - AVStream * RecorderTrack::GetStream() const - { - return stream_; - } - - AVPacket * RecorderTrack::Stamp(RecordedFrame & frame, int64_t start_us) + void RecorderTrack::Timestamp(RecordedFrame & frame, int64_t start_us) { - AVPacket * packet = frame.packet.get(); - const AVRational track_time_base{ 1, clock_rate_ }; - // Where the clock puts the frame, which is what a track starts from, // and what it falls back on if its RTP timestamps stop making sense. int64_t clock_pts = av_rescale(frame.time_us - start_us, clock_rate_, 1000000); @@ -381,26 +412,8 @@ namespace ffmpeg pts = clock_pts; } - // Every container wants increasing timestamps, and some want them - // strictly increasing even where frames share an RTP timestamp. - int64_t stream_pts = av_rescale_q(std::max(pts, 0), track_time_base, stream_->time_base); - - if (stream_pts <= last_pts_) { - stream_pts = last_pts_ + 1; - } - - last_pts_ = stream_pts; - - packet->pts = stream_pts; - packet->dts = stream_pts; - packet->stream_index = stream_->index; - packet->time_base = stream_->time_base; - - if (frame.key_frame || media_type_ == AVMEDIA_TYPE_AUDIO) { - packet->flags |= AV_PKT_FLAG_KEY; - } - - return packet; + frame.pts = pts; + frame.timeline_us = av_rescale(pts, 1000000, clock_rate_); } bool RecorderTrack::DescribeVideo(const RecordedFrame & frame) diff --git a/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorder.java b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorder.java index 2ca9b7e50..2ac25eff0 100644 --- a/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorder.java +++ b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorder.java @@ -18,12 +18,21 @@ import java.io.IOException; import java.nio.file.Files; +import java.nio.file.NoSuchFileException; import java.nio.file.Path; +import java.nio.file.Paths; import java.nio.file.StandardCopyOption; +import java.time.Duration; +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.Collections; +import java.util.Deque; import java.util.List; +import java.util.Map; import java.util.Objects; import java.util.UUID; import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ExecutionException; import java.util.concurrent.ExecutorService; import java.util.concurrent.CopyOnWriteArrayList; @@ -71,6 +80,12 @@ * is asked to replace it, which happens only once the new recording is * finished: a recording that fails or gets no media costs nothing. *

+ * A recorder created with {@link #MediaRecorder(SegmentOptions)} splits the + * recording into segments, files that each begin with a key frame and play on + * their own, ending one by its duration or size and keeping as many as the + * options say. To keep only the last seconds in memory and save them on + * demand, see {@link ReplayBuffer}. + *

* How it behaves: *

    *
  • A video track is recorded from its first key frame, and the recorder @@ -104,12 +119,37 @@ public class MediaRecorder implements AutoCloseable { private final Object lock = new Object(); - /** The file being written: the file itself, or one beside it to replace it. */ + /** + * The file being written: the file itself, or one beside it to replace + * it. Null for segments and replays, whose files the native recorder + * creates or is given. + */ private final Path output; - /** Where the recording is meant to end up, or stays if it cannot. */ + /** + * Where the recording is meant to end up, or stays if it cannot; for + * segments, the last one finished. + */ private volatile Path file; + /** How to split the recording, or null for a single file. */ + private final SegmentOptions segments; + + /** The segments kept so far, oldest first. Guarded by itself. */ + private final Deque keptSegments = new ArrayDeque<>(); + + /** What the kept segments take together. Guarded by keptSegments. */ + private long keptBytes; + + /** Whether this records into a replay buffer rather than a file. */ + private final boolean replay; + + /** The replays asked for and not saved yet, by their id. */ + private final Map pendingSaves = new ConcurrentHashMap<>(); + + /** The id of the next replay. Guarded by lock. */ + private int nextSaveId; + /** * How to ask each track for a key frame, by track index. Filled before * the start, read by the writer thread after it. @@ -182,6 +222,8 @@ public MediaRecorder(Path file, boolean overwrite) throws IOException { } this.file = target; + this.segments = null; + this.replay = false; // Created here rather than by the native recorder, which would empty // a file that came into being since the check. this.output = overwrite ? createTemporaryFile(target) : Files.createFile(target); @@ -196,6 +238,73 @@ public MediaRecorder(Path file, boolean overwrite) throws IOException { } } + /** + * Creates a recorder that splits the recording into segments, as the + * given options say. + *

    + * Each segment is a file of its own that begins with a key frame of every + * video track, so that it plays without the ones before. Its timestamps + * begin at zero, and the tracks keep their sync across segments. A + * segment's file is created only when the segment begins, numbered on + * from the highest number already in the directory, so a recorder started + * again goes on after the last segment and never empties a file: a + * number whose file exists in the meantime is skipped. + *

    + * When a segment is due to end, its video tracks are asked for key + * frames, and the next segment begins at the first one. A video track + * whose key frame comes later goes on in the segment before until then, + * so that neither of the two has a gap; one that sends none within a few + * seconds starts the new segment at its next key frame. + *

    + * A track that changes its codec, which a single file cannot hold, goes + * on with the new codec in the next segment, which begins as soon as the + * new codec is known. + *

    + * Each finished segment is reported to {@link + * MediaRecorderListener#onSegmentFinished(MediaRecorderSegment)}, and the + * segments kept so far are listed by {@link #getSegments()}. + * + * @param segments How to split the recording. + * + * @throws NoSuchFileException If the directory of the segments does not + * exist. + * @throws IOException If the directory cannot be read. + */ + public MediaRecorder(SegmentOptions segments) throws IOException { + Objects.requireNonNull(segments, "Segments are null"); + + if (!Files.isDirectory(segments.getDirectory())) { + throw new NoSuchFileException(segments.getDirectory().toString(), null, "Not a directory"); + } + + Duration maxDuration = segments.getMaxDuration(); + long maxDurationUs = maxDuration != null ? maxDuration.toNanos() / 1000 : 0; + + this.file = null; + this.output = null; + this.segments = segments; + this.replay = false; + this.handle = createSegments(segments.pathPrefix(), segments.nameSuffix(), segments.width(), + segments.nextIndex(), maxDurationUs, segments.getMaxSize(), NativeApi.tableAddress()); + } + + /** A recorder for a {@link ReplayBuffer}. */ + private MediaRecorder(Duration window, long maxBytes) throws IOException { + this.file = null; + this.output = null; + this.segments = null; + this.replay = true; + this.handle = createReplay(window.toNanos() / 1000, maxBytes, NativeApi.tableAddress()); + } + + /** + * Creates the recorder of a replay buffer, which keeps what arrives in + * memory for {@link #saveReplay(Path)}. + */ + static MediaRecorder replayBuffer(Duration window, long maxBytes) throws IOException { + return new MediaRecorder(window, maxBytes); + } + /** * Sets what to report to, replacing whatever was set before. A listener of * {@code null} stops reporting. @@ -359,7 +468,12 @@ public boolean stop() { result = MediaRecorderResult.values()[stop(handle)]; state = MediaRecorderState.STOPPED; - finishOutput(); + if (output != null) { + finishOutput(); + } + + // The writer has ended, and answered every replay it took. + failPendingSaves(new IllegalStateException("The replay buffer was stopped")); if (events != null) { // Lets the reports already queued run, then ends the thread. @@ -417,6 +531,9 @@ public MediaRecorderStats getStats() { * the file given to the constructor, or the temporary file beside it * if the recording could not take the place of that file, as {@link * MediaRecorderListener#onError(String)} was told. + *

    + * A recorder that records in segments returns the segment it finished + * last, or {@code null} before the first one is finished. * * @return The file of the recording. */ @@ -424,6 +541,51 @@ public Path getFile() { return file; } + /** + * Returns the segments of the recording that are kept, oldest first: those + * finished so far, without those the options had deleted. Once the + * recorder is stopped, the last segment is among them. + * + * @return The segments, or an empty list for a recorder that does not + * record in segments. + */ + public List getSegments() { + synchronized (keptSegments) { + return Collections.unmodifiableList(new ArrayList<>(keptSegments)); + } + } + + /** + * Saves what the replay buffer holds into the given file, which must not + * exist yet. The future completes on the listener's thread. + */ + CompletableFuture saveReplay(Path file) throws IOException { + Objects.requireNonNull(file, "File is null"); + + synchronized (lock) { + checkState(MediaRecorderState.RECORDING); + + Path target = file.toAbsolutePath(); + + // Created here, so that a file that exists is never emptied. + Files.createFile(target); + + int id = nextSaveId++; + CompletableFuture future = new CompletableFuture<>(); + + pendingSaves.put(id, new PendingSave(target, future)); + + if (!saveReplay(handle, id, target.toString())) { + pendingSaves.remove(id); + deleteQuietly(target); + + throw new IllegalStateException("The replay buffer failed, as the listener was told"); + } + + return future; + } + } + /** * Stops the recording if it still runs and releases the native recorder. * Closing a recorder that is closed does nothing. @@ -492,14 +654,67 @@ private void replaceFile() throws IOException { } private void deleteOutput() { + deleteQuietly(output); + } + + private static void deleteQuietly(Path path) { try { - Files.deleteIfExists(output); + Files.deleteIfExists(path); } catch (IOException e) { // The file stays behind, empty; there is nothing else to do. } } + /** Fails the replays that were asked for and will not be saved. */ + private void failPendingSaves(Exception cause) { + for (Integer id : new ArrayList<>(pendingSaves.keySet())) { + PendingSave save = pendingSaves.remove(id); + + if (save != null) { + post(() -> { + deleteQuietly(save.file); + save.future.completeExceptionally(cause); + }); + } + } + } + + /** + * Keeps the segment, and returns the oldest ones the options no longer + * keep, to be deleted. + */ + private List keep(MediaRecorderSegment segment) { + List expired = new ArrayList<>(); + int maxSegments = segments.getMaxSegments(); + long maxTotalSize = segments.getMaxTotalSize(); + + synchronized (keptSegments) { + keptSegments.addLast(segment); + keptBytes += segment.getSize(); + + while (keptSegments.size() > 1 + && ((maxSegments > 0 && keptSegments.size() > maxSegments) + || (maxTotalSize > 0 && keptBytes > maxTotalSize))) { + MediaRecorderSegment oldest = keptSegments.removeFirst(); + + keptBytes -= oldest.getSize(); + expired.add(oldest); + } + } + + return expired; + } + + private static long sizeOf(Path path) { + try { + return Files.size(path); + } + catch (IOException e) { + return 0; + } + } + /** Called with the lock held, in the idle state. */ private void addTrack(EncodedFrames.Source source) { addTrack(source.take(), source::requestKeyFrame); @@ -642,8 +857,97 @@ private void onNativeKeyFrameNeeded(int track) { }); } + /** Called by native code on the writer thread. */ + private void onNativeSegmentFinished(long index, String path, long startUs, long durationUs, int result) { + // In the order of the native MediaRecorder::Result. + MediaRecorderResult outcome = MediaRecorderResult.values()[result]; + Path segmentFile = Paths.get(path); + + if (!outcome.keepsFile()) { + // Nothing in it plays; what went wrong was reported already. + post(() -> deleteQuietly(segmentFile)); + return; + } + + MediaRecorderSegment segment = new MediaRecorderSegment(index, segmentFile, startUs, durationUs, + sizeOf(segmentFile), outcome); + + // Kept here, so that the segments are known once the recorder is + // stopped; deleted on the event thread, which the writer does not + // wait for. + List expired = keep(segment); + + file = segmentFile; + + post(() -> { + MediaRecorderListener current = listener; + + if (current != null) { + current.onSegmentFinished(segment); + } + + for (MediaRecorderSegment old : expired) { + try { + Files.deleteIfExists(old.getFile()); + } + catch (IOException e) { + current = listener; + + if (current != null) { + current.onWarning("Deleting the old segment " + old.getFile() + " failed: " + e); + } + } + } + }); + } + + /** Called by native code on the writer thread. */ + private void onNativeReplaySaved(int id, int result, long startUs, long durationUs, String error) { + PendingSave save = pendingSaves.remove(id); + + if (save == null) { + return; + } + + MediaRecorderResult outcome = MediaRecorderResult.values()[result]; + + if (!outcome.keepsFile()) { + post(() -> { + deleteQuietly(save.file); + + if (outcome == MediaRecorderResult.EMPTY) { + save.future.completeExceptionally(new IllegalStateException("The replay buffer holds no media")); + } + else { + save.future.completeExceptionally(new IOException(error)); + } + }); + return; + } + + MediaRecorderSegment segment = new MediaRecorderSegment(id, save.file, startUs, durationUs, + sizeOf(save.file), outcome); + + post(() -> { + MediaRecorderListener current = listener; + + if (error != null && current != null) { + current.onWarning(error); + } + + save.future.complete(segment); + }); + } + private native long create(String path, long tableAddress) throws IOException; + private native long createSegments(String prefix, String suffix, int width, long firstIndex, + long maxDurationUs, long maxBytes, long tableAddress) throws IOException; + + private native long createReplay(long windowUs, long maxBytes, long tableAddress) throws IOException; + + private static native boolean saveReplay(long handle, int id, String path); + private static native int addTrack(long handle, long frames); private static native void start(long handle); @@ -654,4 +958,19 @@ private void onNativeKeyFrameNeeded(int track) { private static native void dispose(long handle); + + /** A replay that was asked for: where it goes, and who waits for it. */ + private static final class PendingSave { + + final Path file; + + final CompletableFuture future; + + + PendingSave(Path file, CompletableFuture future) { + this.file = file; + this.future = future; + } + } + } diff --git a/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderListener.java b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderListener.java index c9b93146e..1f66557aa 100644 --- a/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderListener.java +++ b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderListener.java @@ -58,4 +58,19 @@ default void onWarning(String message) { default void onError(String message) { } + /** + * A segment of a recorder that records in {@link SegmentOptions segments} + * was finished and closed, the last one when the recorder is stopped. A + * segment that failed before any media went into it is deleted and not + * reported here, only to {@link #onError(String)}. + *

    + * The oldest segments that the options do not keep are deleted right + * after this call returns, so a segment to be kept beyond them has to be + * copied or moved by then. One that is moved away is no longer deleted. + * + * @param segment The segment that was finished. + */ + default void onSegmentFinished(MediaRecorderSegment segment) { + } + } diff --git a/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderSegment.java b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderSegment.java new file mode 100644 index 000000000..334de0f4d --- /dev/null +++ b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderSegment.java @@ -0,0 +1,114 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.media.recorder; + +import java.nio.file.Path; +import java.time.Duration; + +/** + * A file a recording was written into, and finished: a segment of a {@link + * MediaRecorder} that records in {@link SegmentOptions segments}, or a replay + * saved by a {@link ReplayBuffer}. It begins with a key frame of every video + * track and plays on its own. + * + * @author Alex Andres + */ +public final class MediaRecorderSegment { + + private final long index; + + private final Path file; + + private final Duration start; + + private final Duration duration; + + private final long size; + + private final MediaRecorderResult result; + + + MediaRecorderSegment(long index, Path file, long startUs, long durationUs, long size, + MediaRecorderResult result) { + this.index = index; + this.file = file; + this.start = Duration.ofNanos(startUs * 1000); + this.duration = Duration.ofNanos(durationUs * 1000); + this.size = size; + this.result = result; + } + + /** + * Returns the number of the segment, which its file name holds, or of the + * replay, counting the replays a buffer saved from 0. + * + * @return The number. + */ + public long getIndex() { + return index; + } + + /** + * @return The file. + */ + public Path getFile() { + return file; + } + + /** + * Returns where the file begins in the recording, counted from when the + * recorder or buffer was started. A file's own timestamps begin at zero. + * + * @return The offset of the first frame. + */ + public Duration getStart() { + return start; + } + + /** + * @return The time from the first frame in the file to its last. + */ + public Duration getDuration() { + return duration; + } + + /** + * @return The size of the file once it was finished, in bytes. + */ + public long getSize() { + return size; + } + + /** + * Returns whether everything went into the file: {@link + * MediaRecorderResult#COMPLETE}, or {@link MediaRecorderResult#PARTIAL} if + * writing, finishing or closing it failed, and it ends early or lacks its + * index. + * + * @return The result of this file. + */ + public MediaRecorderResult getResult() { + return result; + } + + @Override + public String toString() { + return "MediaRecorderSegment[index=" + index + ", file=" + file + ", start=" + start + ", duration=" + + duration + ", size=" + size + ", result=" + result + "]"; + } + +} diff --git a/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/ReplayBuffer.java b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/ReplayBuffer.java new file mode 100644 index 000000000..afff760a6 --- /dev/null +++ b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/ReplayBuffer.java @@ -0,0 +1,284 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.media.recorder; + +import java.io.IOException; +import java.nio.file.Path; +import java.time.Duration; +import java.util.Objects; +import java.util.concurrent.CompletableFuture; + +import dev.onvoid.webrtc.RTCRtpReceiver; +import dev.onvoid.webrtc.RTCRtpSender; +import dev.onvoid.webrtc.client.RemoteTrack; +import dev.onvoid.webrtc.client.Sender; + +/** + * Keeps the last seconds of what a peer connection sends or receives in + * memory, and saves them into a file on demand: "save the last 30 seconds". + * Like a {@link MediaRecorder}, it takes the encoded frames as they are, + * without decoding or re-encoding them, so keeping them costs memory, not + * CPU. + *

    + * Example: + *

    {@code
    + * try (ReplayBuffer buffer = new ReplayBuffer(Duration.ofSeconds(30))) {
    + *     buffer.addTrack(videoReceiver);
    + *     buffer.addTrack(audioReceiver);
    + *     buffer.start();
    + *
    + *     // ... something happens worth keeping ...
    + *
    + *     buffer.save(Paths.get("replay.mkv"))
    + *             .thenAccept(replay -> System.out.println("Saved " + replay.getDuration()));
    + * }
    + * }
    + *

    + * A replay begins with a key frame of every video track, so that it plays on + * its own: at the last key frame before the window, which therefore holds at + * least the window, and a few seconds more. Since WebRTC sends key frames + * rarely of its own accord, the buffer asks its video tracks for one now and + * then: every third of the window, at least every two seconds and at most + * every ten. A replay holds what the buffer took up to the moment it was asked + * for, and the buffer goes on taking frames while the replay is written. + *

    + * What the buffer holds is limited twice: by the window, and by a number of + * bytes, {@value #DEFAULT_MAX_BYTES} unless the constructor is given + * another. Beyond the limit in bytes, the oldest frames go first, and a + * replay is shorter than the window. + *

    + * The tracks behave as in a {@link MediaRecorder}, end-to-end encrypted ones + * included, with two differences: + * a track is kept as soon as it is known, without waiting for the others; + * and a track that changes its codec is kept with the new one from then on, + * having its frames in the old one dropped. A track whose codec the file + * of a replay cannot hold is left out of that replay, and reported to the + * {@link MediaRecorderListener#onWarning(String) listener}. + * + * @author Alex Andres + */ +public class ReplayBuffer implements AutoCloseable { + + /** The most a buffer holds unless told otherwise, 256 MB. */ + public static final long DEFAULT_MAX_BYTES = 256L * 1024 * 1024; + + private final MediaRecorder recorder; + + private final Duration window; + + + /** + * Creates a buffer for replays of the given length, holding at most + * {@value #DEFAULT_MAX_BYTES} bytes. + * + * @param window How far back a replay reaches, at least a second. + * + * @throws IOException If the native buffer cannot be created. + */ + public ReplayBuffer(Duration window) throws IOException { + this(window, DEFAULT_MAX_BYTES); + } + + /** + * Creates a buffer for replays of the given length, holding at most the + * given number of bytes. + * + * @param window How far back a replay reaches, at least a second. + * @param maxBytes The most the buffer holds, more than 0. + * + * @throws IOException If the native buffer cannot be created. + */ + public ReplayBuffer(Duration window, long maxBytes) throws IOException { + Objects.requireNonNull(window, "Window is null"); + + if (window.compareTo(Duration.ofSeconds(1)) < 0) { + throw new IllegalArgumentException("A replay reaches back at least a second, not " + window); + } + if (maxBytes <= 0) { + throw new IllegalArgumentException("The buffer must hold more than 0 bytes, got " + maxBytes); + } + + this.window = window; + this.recorder = MediaRecorder.replayBuffer(window, maxBytes); + } + + /** + * Sets what to report to, replacing whatever was set before: {@link + * MediaRecorderListener#onStarted()} once the first frames are kept, + * warnings, and {@link MediaRecorderListener#onError(String)} if the + * buffer ran out of native memory and keeps nothing more. A listener of + * {@code null} stops reporting. + * + * @param listener The listener, or {@code null}. + */ + public void setListener(MediaRecorderListener listener) { + recorder.setListener(listener); + } + + /** + * Keeps what the given sender sends, as it comes out of the encoder. + * + * @param sender The sender to keep. + * + * @throws IllegalStateException If the buffer was started or closed, + * or the track's transform does not + * allow recording. + * @throws IllegalArgumentException If the sender was disposed. + * + * @see MediaRecorder#addTrack(RTCRtpSender) + */ + public void addTrack(RTCRtpSender sender) { + recorder.addTrack(sender); + } + + /** + * Keeps what the given receiver receives, as it goes into the decoder. + * + * @param receiver The receiver to keep. + * + * @throws IllegalStateException If the buffer was started or closed, + * or the track's transform does not + * allow recording. + * @throws IllegalArgumentException If the receiver was disposed. + * + * @see MediaRecorder#addTrack(RTCRtpReceiver) + */ + public void addTrack(RTCRtpReceiver receiver) { + recorder.addTrack(receiver); + } + + /** + * Keeps what a sender of the client API sends. + * + * @param sender The sender to keep. + * + * @throws IllegalStateException If the buffer was started or closed, + * or the track's transform does not + * allow recording. + * @throws IllegalArgumentException If the sender was removed, or its peer + * closed. + * + * @see MediaRecorder#addTrack(Sender) + */ + public void addTrack(Sender sender) { + recorder.addTrack(sender); + } + + /** + * Keeps what a remote track of the client API receives. + * + * @param track The remote track to keep. + * + * @throws IllegalStateException If the buffer was started or closed, + * or the track's transform does not + * allow recording. + * @throws IllegalArgumentException If the track ended. + * + * @see MediaRecorder#addTrack(RemoteTrack) + */ + public void addTrack(RemoteTrack track) { + recorder.addTrack(track); + } + + /** + * Starts keeping the tracks added so far. If that fails, the buffer is as + * it was before and may be started again. + * + * @throws IllegalStateException If the buffer has no tracks, or was + * started or closed before. + */ + public void start() { + recorder.start(); + } + + /** + * Saves what the buffer holds of the last {@link #getWindow() window} into + * the given file, which must not exist yet; its extension picks the + * container, as for a {@link MediaRecorder}. The file is created at once, + * and written by the buffer's own thread. + *

    + * The future completes on the listener's thread, with the replay once it + * is finished and closed; it is {@link MediaRecorderResult#PARTIAL} if + * writing it failed after media went into it, which the listener's + * {@link MediaRecorderListener#onWarning(String)} is told. It completes + * exceptionally, and the file is deleted, if nothing could be written: + * with an {@link IOException} if writing failed, and an {@link + * IllegalStateException} if the buffer held nothing to save, or was + * stopped first. + * + * @param file Where to save the replay. + * + * @return The replay, once it is saved. + * + * @throws IllegalStateException If the buffer is not + * started, was stopped, + * or failed. + * @throws java.nio.file.FileAlreadyExistsException If the file exists. + * @throws IOException If the file cannot be + * created. + */ + public CompletableFuture save(Path file) throws IOException { + return recorder.saveReplay(file); + } + + /** + * Stops keeping frames and lets go of what the buffer holds, once the + * replays asked for so far are saved. Stopping a buffer that is stopped + * does nothing. + */ + public void stop() { + recorder.stop(); + } + + /** + * Returns what the buffer is doing: {@link MediaRecorderState#RECORDING} + * while it keeps frames. + * + * @return The buffer state. + */ + public MediaRecorderState getState() { + return recorder.getState(); + } + + /** + * Returns what the buffer lost so far, before it could keep it. + * + * @return The numbers as of now. + * + * @see MediaRecorder#getStats() + */ + public MediaRecorderStats getStats() { + return recorder.getStats(); + } + + /** + * @return How far back a replay reaches. + */ + public Duration getWindow() { + return window; + } + + /** + * Stops the buffer if it still runs and releases the native buffer. + * Closing a buffer that is closed does nothing. + */ + @Override + public void close() { + recorder.close(); + } + +} diff --git a/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/SegmentOptions.java b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/SegmentOptions.java new file mode 100644 index 000000000..ab4326d0d --- /dev/null +++ b/webrtc-media/src/main/java/dev/onvoid/webrtc/media/recorder/SegmentOptions.java @@ -0,0 +1,401 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.media.recorder; + +import java.io.IOException; +import java.nio.file.DirectoryStream; +import java.nio.file.Files; +import java.nio.file.Path; +import java.time.Duration; +import java.util.Objects; + +/** + * How a {@link MediaRecorder} splits a recording into segments, and how many + * of them it keeps. + *

    + * Segments are named after a pattern whose file name holds the segment's + * number as {@code %d}, or zero-padded to a width as in {@code %05d}; a + * literal percent sign is written {@code %%}. The extension picks the + * container of every segment, as it does for a single file: + *

    {@code
    + * SegmentOptions segments = SegmentOptions.builder(Paths.get("recordings", "camera-%05d.mkv"))
    + *         .maxDuration(Duration.ofMinutes(10))
    + *         .maxTotalSize(20L * 1024 * 1024 * 1024)
    + *         .build();
    + * }
    + *

    + * A segment ends once it lasts {@link Builder#maxDuration(Duration) long + * enough} or {@link Builder#maxSize(long) holds enough}, at the next key frame, + * since every segment has to begin with one to play on its own. Which limits + * apply, at least one of the two, is up to the builder; once a limit is + * reached, the recorder asks for a key frame, so a segment ends a moment after + * it, not much later. + *

    + * Without limits on what is kept, every segment stays. With them, the oldest + * segments of the recording are deleted whenever a segment is finished, until + * the rest are within them. The newest segment is always kept. + * + * @author Alex Andres + */ +public final class SegmentOptions { + + private final Path pattern; + + private final Path directory; + + /** The file name before the number, and after it. */ + private final String namePrefix; + + private final String nameSuffix; + + /** How many digits the number has at least. */ + private final int width; + + private final Duration maxDuration; + + private final long maxSize; + + private final int maxSegments; + + private final long maxTotalSize; + + + private SegmentOptions(Builder builder) { + this.pattern = builder.pattern; + this.directory = builder.directory; + this.namePrefix = builder.namePrefix; + this.nameSuffix = builder.nameSuffix; + this.width = builder.width; + this.maxDuration = builder.maxDuration; + this.maxSize = builder.maxSize; + this.maxSegments = builder.maxSegments; + this.maxTotalSize = builder.maxTotalSize; + } + + /** + * Returns a builder for segments named after the given pattern, whose file + * name holds the number of a segment as {@code %d} or {@code %0Nd}. The + * directory must exist when the recorder is created. + * + * @param pattern The path of a segment, with its number as a placeholder. + * + * @return A builder without limits. + * + * @throws IllegalArgumentException If the file name holds no placeholder, + * more than one, or a percent sign that is + * not one or {@code %%}. + */ + public static Builder builder(Path pattern) { + return new Builder(pattern); + } + + /** + * @return The pattern segments are named after. + */ + public Path getPattern() { + return pattern; + } + + /** + * @return How long a segment lasts before it ends at the next key frame, + * or {@code null} for no limit. + */ + public Duration getMaxDuration() { + return maxDuration; + } + + /** + * @return How many bytes a segment holds before it ends at the next key + * frame, or 0 for no limit. + */ + public long getMaxSize() { + return maxSize; + } + + /** + * @return How many segments are kept, or 0 for all of them. + */ + public int getMaxSegments() { + return maxSegments; + } + + /** + * @return How many bytes the segments that are kept take together at + * most, or 0 for no limit. + */ + public long getMaxTotalSize() { + return maxTotalSize; + } + + @Override + public String toString() { + return "SegmentOptions[pattern=" + pattern + ", maxDuration=" + maxDuration + ", maxSize=" + maxSize + + ", maxSegments=" + maxSegments + ", maxTotalSize=" + maxTotalSize + "]"; + } + + Path getDirectory() { + return directory; + } + + /** + * @return The path of a segment up to its number, as the native recorder + * puts it together. + */ + String pathPrefix() { + String dir = directory.toString(); + String separator = directory.getFileSystem().getSeparator(); + + return (dir.endsWith(separator) ? dir : dir + separator) + namePrefix; + } + + String nameSuffix() { + return nameSuffix; + } + + int width() { + return width; + } + + /** + * Returns the number that follows the highest one of the segments in the + * directory, so that a recording started again goes on after the last, + * or 0 if there are none. + */ + long nextIndex() throws IOException { + long highest = -1; + + try (DirectoryStream files = Files.newDirectoryStream(directory)) { + for (Path file : files) { + highest = Math.max(highest, indexOf(file.getFileName().toString())); + } + } + + return highest + 1; + } + + /** + * @return The number of the segment with the given file name, or -1 if + * the name is not one of a segment. + */ + long indexOf(String name) { + if (name.length() <= namePrefix.length() + nameSuffix.length() + || !name.startsWith(namePrefix) || !name.endsWith(nameSuffix)) { + return -1; + } + + String digits = name.substring(namePrefix.length(), name.length() - nameSuffix.length()); + + // Far below the range of a long, which no recording reaches. + if (digits.length() > 18) { + return -1; + } + for (int i = 0; i < digits.length(); i++) { + char c = digits.charAt(i); + + if (c < '0' || c > '9') { + return -1; + } + } + + return Long.parseLong(digits); + } + + + + /** Builds {@link SegmentOptions}. */ + public static final class Builder { + + private final Path pattern; + + private final Path directory; + + private String namePrefix; + + private String nameSuffix; + + private int width; + + private Duration maxDuration; + + private long maxSize; + + private int maxSegments; + + private long maxTotalSize; + + + private Builder(Path pattern) { + Objects.requireNonNull(pattern, "Pattern is null"); + + Path absolute = pattern.toAbsolutePath(); + Path name = absolute.getFileName(); + + if (name == null) { + throw new IllegalArgumentException("The pattern " + pattern + " has no file name"); + } + + this.pattern = pattern; + this.directory = absolute.getParent(); + + parse(name.toString()); + } + + /** + * Ends a segment once it lasts this long, at the next key frame. + * + * @param duration At least a second. + * + * @return This builder. + */ + public Builder maxDuration(Duration duration) { + Objects.requireNonNull(duration, "Duration is null"); + + if (duration.compareTo(Duration.ofSeconds(1)) < 0) { + throw new IllegalArgumentException("A segment lasts at least a second, not " + duration); + } + + this.maxDuration = duration; + return this; + } + + /** + * Ends a segment once it holds this many bytes, at the next key frame, + * so that it ends up somewhat larger. + * + * @param bytes More than 0. + * + * @return This builder. + */ + public Builder maxSize(long bytes) { + if (bytes <= 0) { + throw new IllegalArgumentException("The size must be positive, got " + bytes); + } + + this.maxSize = bytes; + return this; + } + + /** + * Keeps no more than this many segments of the recording, deleting the + * oldest. + * + * @param count More than 0. + * + * @return This builder. + */ + public Builder maxSegments(int count) { + if (count <= 0) { + throw new IllegalArgumentException("The count must be positive, got " + count); + } + + this.maxSegments = count; + return this; + } + + /** + * Keeps no more segments of the recording than take this many bytes + * together, deleting the oldest. The newest is kept even if it is + * larger, and the segment being written does not count, so the + * recording takes up to this much and one segment more. + * + * @param bytes More than 0. + * + * @return This builder. + */ + public Builder maxTotalSize(long bytes) { + if (bytes <= 0) { + throw new IllegalArgumentException("The size must be positive, got " + bytes); + } + + this.maxTotalSize = bytes; + return this; + } + + /** + * @return The options. + * + * @throws IllegalStateException If neither a duration nor a size ends + * a segment. + */ + public SegmentOptions build() { + if (maxDuration == null && maxSize == 0) { + throw new IllegalStateException("A segment ends by its duration or its size; neither is set"); + } + + return new SegmentOptions(this); + } + + private void parse(String name) { + StringBuilder prefix = new StringBuilder(); + StringBuilder suffix = new StringBuilder(); + StringBuilder current = prefix; + boolean found = false; + int i = 0; + + while (i < name.length()) { + char c = name.charAt(i++); + + if (c != '%') { + current.append(c); + continue; + } + if (i < name.length() && name.charAt(i) == '%') { + current.append('%'); + i++; + continue; + } + + int digits = i; + + while (i < name.length() && name.charAt(i) >= '0' && name.charAt(i) <= '9') { + i++; + } + + String flags = name.substring(digits, i); + + if (i >= name.length() || name.charAt(i) != 'd' + || (!flags.isEmpty() && (flags.charAt(0) != '0' || flags.length() < 2))) { + throw new IllegalArgumentException("The file name " + name + + " has a placeholder other than %d or %0Nd, or a % that should be %%"); + } + if (found) { + throw new IllegalArgumentException("The file name " + name + " has more than one placeholder"); + } + + int padding = flags.isEmpty() ? 1 : Integer.parseInt(flags.substring(1)); + + if (padding < 1 || padding > 18) { + throw new IllegalArgumentException("The number in " + name + " is padded to 1 to 18 digits"); + } + + i++; + found = true; + width = padding; + current = suffix; + } + + if (!found) { + throw new IllegalArgumentException("The file name " + name + " has no placeholder for the number, " + + "such as %d or %05d"); + } + + namePrefix = prefix.toString(); + nameSuffix = suffix.toString(); + } + } + +} diff --git a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/RecordingProbe.java b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/RecordingProbe.java new file mode 100644 index 000000000..e0fe43acc --- /dev/null +++ b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/RecordingProbe.java @@ -0,0 +1,99 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.media.recorder; + +import java.io.IOException; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.List; + +import dev.onvoid.webrtc.media.player.FFmpeg; + +/** + * Reads a recorded file packet by packet, which shows what its header alone + * does not: where each stream begins, and whether at a key frame. It lives in + * the tests so that nothing else can reach it. + * + * @author Alex Andres + */ +final class RecordingProbe { + + static { + FFmpeg.load(); + } + + /** How many values the native probe reports per stream. */ + private static final int VALUES = 5; + + + private RecordingProbe() { + // Static access only. + } + + /** + * @return The streams of the file, in the order the file has them. + */ + static List streamsOf(Path file) throws IOException { + long[] values = streams(file.toString()); + List list = new ArrayList<>(); + + for (int i = 0; i + VALUES <= values.length; i += VALUES) { + list.add(new Stream(values[i] == 0, values[i] == 1, values[i + 1] == 1, values[i + 2], + values[i + 3], values[i + 4])); + } + + return list; + } + + private static native long[] streams(String path) throws IOException; + + + /** What a file holds of one stream. */ + static final class Stream { + + final boolean video; + + final boolean audio; + + /** Whether the first packet is a key frame. */ + final boolean startsWithKeyFrame; + + final long firstPtsUs; + + final long lastPtsUs; + + final long packets; + + + Stream(boolean video, boolean audio, boolean startsWithKeyFrame, long firstPtsUs, long lastPtsUs, + long packets) { + this.video = video; + this.audio = audio; + this.startsWithKeyFrame = startsWithKeyFrame; + this.firstPtsUs = firstPtsUs; + this.lastPtsUs = lastPtsUs; + this.packets = packets; + } + + @Override + public String toString() { + return (video ? "video" : audio ? "audio" : "other") + "[key=" + startsWithKeyFrame + ", first=" + + firstPtsUs + ", last=" + lastPtsUs + ", packets=" + packets + "]"; + } + } + +} diff --git a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/ReplayBufferTest.java b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/ReplayBufferTest.java new file mode 100644 index 000000000..bb1e2962a --- /dev/null +++ b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/ReplayBufferTest.java @@ -0,0 +1,239 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.media.recorder; + +import static dev.onvoid.webrtc.media.recorder.SegmentedRecorderTest.assertPlaysOnItsOwn; +import static dev.onvoid.webrtc.media.recorder.SegmentedRecorderTest.readInfo; +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.charset.StandardCharsets; +import java.nio.file.FileAlreadyExistsException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.time.Duration; +import java.util.concurrent.TimeUnit; + +import dev.onvoid.webrtc.PeerConnectionFactory; +import dev.onvoid.webrtc.media.audio.AudioDeviceModule; +import dev.onvoid.webrtc.media.audio.AudioLayer; +import dev.onvoid.webrtc.media.player.MediaInfo; + +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.TestInstance; +import org.junit.jupiter.api.io.TempDir; +import org.junit.jupiter.api.parallel.Execution; +import org.junit.jupiter.api.parallel.ExecutionMode; + +/** + * Tests keeping the last seconds of a call and saving them, checked by + * reading the replays back. + */ +@TestInstance(TestInstance.Lifecycle.PER_CLASS) +@Execution(ExecutionMode.SAME_THREAD) +class ReplayBufferTest { + + private AudioDeviceModule audioModule; + private PeerConnectionFactory factory; + + @TempDir + Path tempDir; + + + @BeforeAll + void initFactory() { + audioModule = new AudioDeviceModule(AudioLayer.kDummyAudio); + factory = new PeerConnectionFactory(audioModule); + } + + @AfterAll + void disposeFactory() { + factory.dispose(); + audioModule.dispose(); + } + + @Test + void savesLastSeconds() throws Exception { + SegmentedRecorderTest.Listener listener = new SegmentedRecorderTest.Listener(); + + try (TestCall call = new TestCall(factory); + ReplayBuffer buffer = new ReplayBuffer(Duration.ofSeconds(3))) { + buffer.setListener(listener); + buffer.addTrack(call.getVideoSender()); + buffer.addTrack(call.getAudioSender()); + buffer.start(); + + assertEquals(MediaRecorderState.RECORDING, buffer.getState()); + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(8000); + + Path first = tempDir.resolve("replay-1.mkv"); + MediaRecorderSegment replay = buffer.save(first).get(10, TimeUnit.SECONDS); + + assertEquals(0, replay.getIndex()); + assertEquals(first, replay.getFile()); + assertEquals(MediaRecorderResult.COMPLETE, replay.getResult()); + assertEquals(Files.size(first), replay.getSize()); + + // From the key frame before the window, which the buffer asks for + // every two seconds at a window of three. + long durationMs = replay.getDuration().toMillis(); + + assertTrue(durationMs >= 2900 && durationMs < 6000, replay.toString()); + assertTrue(replay.getStart().toMillis() > 2000, replay.toString()); + + assertPlaysOnItsOwn(first, 2); + + MediaInfo info = readInfo(first); + + assertEquals("vp8", info.getVideoCodec()); + assertEquals("opus", info.getAudioCodec()); + + // The buffer goes on, and saves again. + Thread.sleep(1000); + + Path second = tempDir.resolve("replay-2.webm"); + MediaRecorderSegment next = buffer.save(second).get(10, TimeUnit.SECONDS); + + assertEquals(1, next.getIndex()); + assertTrue(next.getStart().compareTo(replay.getStart()) >= 0, next.toString()); + assertPlaysOnItsOwn(second, 2); + } + + assertNull(listener.error.get()); + assertTrue(listener.warnings.isEmpty(), listener.warnings.toString()); + assertTrue(listener.segments.isEmpty()); + } + + @Test + void limitsWhatItHolds() throws Exception { + try (TestCall call = new TestCall(factory); + ReplayBuffer buffer = new ReplayBuffer(Duration.ofSeconds(10), 50_000)) { + buffer.addTrack(call.getVideoSender()); + buffer.addTrack(call.getAudioSender()); + buffer.start(); + + Thread.sleep(6000); + + Path file = tempDir.resolve("limited.mkv"); + MediaRecorderSegment replay = buffer.save(file).get(10, TimeUnit.SECONDS); + + // Far shorter than the six seconds the window would hold. + assertTrue(replay.getDuration().toMillis() < 4000, replay.toString()); + assertTrue(replay.getSize() < 100_000, replay.toString()); + } + } + + @Test + void keepsNewCodecAfterChange() throws Exception { + SegmentedRecorderTest.Listener listener = new SegmentedRecorderTest.Listener(); + + try (TestCall call = new TestCall(factory); + ReplayBuffer buffer = new ReplayBuffer(Duration.ofSeconds(2))) { + buffer.setListener(listener); + buffer.addTrack(call.getVideoSender()); + buffer.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(1500); + + call.switchVideoCodec("VP9"); + + Thread.sleep(4000); + + Path file = tempDir.resolve("changed.mkv"); + + buffer.save(file).get(10, TimeUnit.SECONDS); + + assertEquals("vp9", readInfo(file).getVideoCodec()); + assertPlaysOnItsOwn(file, 1); + } + + assertTrue(listener.warnings.stream().anyMatch(warning -> warning.contains("changed its codec")), + listener.warnings.toString()); + } + + @Test + void stopSavesWhatWasAskedFor() throws Exception { + try (TestCall call = new TestCall(factory); + ReplayBuffer buffer = new ReplayBuffer(Duration.ofSeconds(2))) { + SegmentedRecorderTest.Listener listener = new SegmentedRecorderTest.Listener(); + + buffer.setListener(listener); + buffer.addTrack(call.getVideoSender()); + buffer.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(1000); + + Path file = tempDir.resolve("at-stop.mkv"); + + java.util.concurrent.CompletableFuture saved = buffer.save(file); + + buffer.stop(); + + assertEquals(MediaRecorderState.STOPPED, buffer.getState()); + assertEquals(file, saved.get(10, TimeUnit.SECONDS).getFile()); + assertPlaysOnItsOwn(file, 1); + + assertThrows(IllegalStateException.class, () -> buffer.save(tempDir.resolve("after-stop.mkv"))); + assertTrue(!Files.exists(tempDir.resolve("after-stop.mkv"))); + } + } + + @Test + void refusesFileThatExists() throws Exception { + byte[] earlier = "earlier recording".getBytes(StandardCharsets.UTF_8); + Path file = Files.write(tempDir.resolve("exists.mkv"), earlier); + + try (TestCall call = new TestCall(factory); + ReplayBuffer buffer = new ReplayBuffer(Duration.ofSeconds(2))) { + buffer.addTrack(call.getAudioSender()); + buffer.start(); + + assertThrows(FileAlreadyExistsException.class, () -> buffer.save(file)); + } + + assertArrayEquals(earlier, Files.readAllBytes(file)); + } + + @Test + void refusesSaveBeforeStart() throws Exception { + try (TestCall call = new TestCall(factory); + ReplayBuffer buffer = new ReplayBuffer(Duration.ofSeconds(2))) { + buffer.addTrack(call.getAudioSender()); + + assertThrows(IllegalStateException.class, () -> buffer.save(tempDir.resolve("early.mkv"))); + assertTrue(!Files.exists(tempDir.resolve("early.mkv"))); + } + } + + @Test + void refusesBadLimits() { + assertThrows(IllegalArgumentException.class, () -> new ReplayBuffer(Duration.ofMillis(500))); + assertThrows(IllegalArgumentException.class, () -> new ReplayBuffer(Duration.ofSeconds(5), 0)); + } + +} diff --git a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/SegmentedRecorderTest.java b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/SegmentedRecorderTest.java new file mode 100644 index 000000000..3654a2ea3 --- /dev/null +++ b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/SegmentedRecorderTest.java @@ -0,0 +1,662 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.media.recorder; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.NoSuchFileException; +import java.nio.file.Path; +import java.time.Duration; +import java.util.List; +import java.util.concurrent.CopyOnWriteArrayList; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicReference; +import java.util.function.BooleanSupplier; +import java.util.stream.Collectors; +import java.util.stream.Stream; + +import dev.onvoid.webrtc.PeerConnectionFactory; +import dev.onvoid.webrtc.RTCRtpReceiver; +import dev.onvoid.webrtc.media.audio.AudioDeviceModule; +import dev.onvoid.webrtc.media.audio.AudioLayer; +import dev.onvoid.webrtc.media.player.MediaInfo; +import dev.onvoid.webrtc.media.player.MediaReader; + +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.TestInstance; +import org.junit.jupiter.api.io.TempDir; +import org.junit.jupiter.api.parallel.Execution; +import org.junit.jupiter.api.parallel.ExecutionMode; + +/** + * Tests recording a call into segments, checked by reading each segment back + * on its own. + */ +@TestInstance(TestInstance.Lifecycle.PER_CLASS) +@Execution(ExecutionMode.SAME_THREAD) +class SegmentedRecorderTest { + + private AudioDeviceModule audioModule; + private PeerConnectionFactory factory; + + @TempDir + Path tempDir; + + + @BeforeAll + void initFactory() { + audioModule = new AudioDeviceModule(AudioLayer.kDummyAudio); + factory = new PeerConnectionFactory(audioModule); + } + + @AfterAll + void disposeFactory() { + factory.dispose(); + audioModule.dispose(); + } + + @Test + void splitsByDuration() throws Exception { + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("call-%05d.mkv")) + .maxDuration(Duration.ofSeconds(2)) + .build(); + Listener listener = new Listener(); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.addTrack(call.getAudioSender()); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + assertNull(recorder.getFile()); + + Thread.sleep(7000); + + assertTrue(recorder.stop()); + assertEquals(MediaRecorderResult.COMPLETE, recorder.getResult()); + + List segments = recorder.getSegments(); + + assertTrue(segments.size() >= 3, "segments: " + segments); + assertEquals(segments.get(segments.size() - 1).getFile(), recorder.getFile()); + + listener.awaitSegments(segments.size()); + + assertEquals(segments, listener.segments); + assertNull(listener.error.get()); + assertTrue(listener.warnings.isEmpty(), listener.warnings.toString()); + + for (int i = 0; i < segments.size(); i++) { + MediaRecorderSegment segment = segments.get(i); + long durationMs = segment.getDuration().toMillis(); + + assertEquals(i, segment.getIndex()); + assertEquals(tempDir.resolve(String.format("call-%05d.mkv", i)), segment.getFile()); + assertEquals(MediaRecorderResult.COMPLETE, segment.getResult()); + assertEquals(Files.size(segment.getFile()), segment.getSize()); + + // Each ends at the key frame asked for once its time is up. + if (i < segments.size() - 1) { + assertTrue(durationMs >= 1900 && durationMs < 3500, segment.toString()); + + MediaRecorderSegment next = segments.get(i + 1); + long gapMs = next.getStart().minus(segment.getStart()).minus(segment.getDuration()).toMillis(); + + // One follows the other, without a gap or an overlap. + assertTrue(Math.abs(gapMs) < 200, "gap " + gapMs + " ms after " + segment); + } + + assertPlaysOnItsOwn(segment.getFile(), 2); + + if (i > 0) { + assertBeginsWithVideo(segment.getFile()); + } + + MediaInfo info = readInfo(segment.getFile()); + + assertEquals("vp8", info.getVideoCodec()); + assertEquals("opus", info.getAudioCodec()); + } + } + } + + @Test + void splitsWebmByDuration() throws Exception { + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("call-%d.webm")) + .maxDuration(Duration.ofSeconds(1)) + .build(); + Listener listener = new Listener(); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.addTrack(call.getAudioSender()); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(3500); + + assertTrue(recorder.stop()); + + List segments = recorder.getSegments(); + + assertTrue(segments.size() >= 2, "segments: " + segments); + + for (MediaRecorderSegment segment : segments) { + assertTrue(segment.getFile().getFileName().toString().matches("call-\\d\\.webm"), segment.toString()); + assertPlaysOnItsOwn(segment.getFile(), 2); + } + } + } + + @Test + void splitsBySize() throws Exception { + long maxSize = 100_000; + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("size-%03d.mkv")) + .maxSize(maxSize) + .build(); + Listener listener = new Listener(); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.addTrack(call.getAudioSender()); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(6000); + + assertTrue(recorder.stop()); + + List segments = recorder.getSegments(); + + assertTrue(segments.size() >= 2, "segments: " + segments); + + for (int i = 0; i < segments.size() - 1; i++) { + // Ends at the next key frame once the limit is reached. + assertTrue(segments.get(i).getSize() >= maxSize, segments.get(i).toString()); + } + for (MediaRecorderSegment segment : segments) { + assertPlaysOnItsOwn(segment.getFile(), 2); + } + } + } + + @Test + void keepsNewestSegments() throws Exception { + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("kept-%02d.mkv")) + .maxDuration(Duration.ofSeconds(1)) + .maxSegments(2) + .build(); + Listener listener = new Listener(); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(5000); + + assertTrue(recorder.stop()); + + List segments = recorder.getSegments(); + + assertEquals(2, segments.size(), segments.toString()); + + long last = segments.get(1).getIndex(); + + assertTrue(last >= 3, segments.toString()); + assertEquals(last - 1, segments.get(0).getIndex()); + + // The older ones are deleted on the listener's thread. + listener.awaitSegments((int) last + 1); + + List expected = segments.stream().map(MediaRecorderSegment::getFile).collect(Collectors.toList()); + + awaitTrue(() -> filesIn(tempDir).equals(expected), () -> "files: " + filesIn(tempDir)); + } + } + + @Test + void keepsSegmentsWithinTotalSize() throws Exception { + long maxTotalSize = 150_000; + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("total-%02d.mkv")) + .maxDuration(Duration.ofSeconds(1)) + .maxTotalSize(maxTotalSize) + .build(); + Listener listener = new Listener(); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.addTrack(call.getAudioSender()); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(6000); + + assertTrue(recorder.stop()); + + List segments = recorder.getSegments(); + long total = segments.stream().mapToLong(MediaRecorderSegment::getSize).sum(); + + assertTrue(segments.size() == 1 || total <= maxTotalSize, segments.toString()); + assertTrue(segments.get(0).getIndex() > 0, "nothing was deleted: " + segments); + + List expected = segments.stream().map(MediaRecorderSegment::getFile).collect(Collectors.toList()); + + awaitTrue(() -> filesIn(tempDir).equals(expected), () -> "files: " + filesIn(tempDir)); + } + } + + @Test + void numbersOnAfterExistingSegments(@TempDir Path dir) throws Exception { + byte[] earlier = "earlier recording".getBytes(StandardCharsets.UTF_8); + Path existing = Files.write(dir.resolve("cam-007.mkv"), earlier); + Files.write(dir.resolve("other-100.mkv"), earlier); + + SegmentOptions options = SegmentOptions.builder(dir.resolve("cam-%03d.mkv")) + .maxDuration(Duration.ofSeconds(60)) + .build(); + Listener listener = new Listener(); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(1000); + + assertTrue(recorder.stop()); + + List segments = recorder.getSegments(); + + assertEquals(1, segments.size()); + assertEquals(8, segments.get(0).getIndex()); + assertEquals(dir.resolve("cam-008.mkv"), segments.get(0).getFile()); + } + + assertArrayEquals(earlier, Files.readAllBytes(existing)); + } + + @Test + void recordsBothSidesInEverySegment() throws Exception { + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("both-%02d.mkv")) + .maxDuration(Duration.ofSeconds(2)) + .build(); + Listener listener = new Listener(); + + try (TestCall call = new TestCall(factory)) { + RTCRtpReceiver video = call.getReceiver(0); + + try (MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.addTrack(video); + recorder.addTrack(call.getAudioSender()); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(6000); + + assertTrue(recorder.stop()); + + List segments = recorder.getSegments(); + + assertTrue(segments.size() >= 2, "segments: " + segments); + + for (int i = 0; i < segments.size(); i++) { + // Both video tracks begin at a key frame of their own. In the + // last segment, one may not have reached it before the stop, + // its frames having gone into the segment before. + assertPlaysOnItsOwn(segments.get(i).getFile(), 3, i == segments.size() - 1); + } + } + finally { + video.dispose(); + } + } + + assertNull(listener.error.get()); + } + + @Test + void changedCodecGoesOnInNextSegment() throws Exception { + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("codec-%02d.mkv")) + .maxDuration(Duration.ofSeconds(60)) + .build(); + Listener listener = new Listener(); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.addTrack(call.getAudioSender()); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + + Thread.sleep(2000); + + call.switchVideoCodec("VP9"); + + Thread.sleep(3000); + + assertTrue(recorder.stop()); + assertEquals(MediaRecorderResult.COMPLETE, recorder.getResult()); + + List segments = recorder.getSegments(); + + assertEquals(2, segments.size(), segments.toString()); + assertEquals("vp8", readInfo(segments.get(0).getFile()).getVideoCodec()); + assertEquals("vp9", readInfo(segments.get(1).getFile()).getVideoCodec()); + + for (MediaRecorderSegment segment : segments) { + assertPlaysOnItsOwn(segment.getFile(), 2); + } + } + + assertTrue(listener.warnings.stream().anyMatch(warning -> warning.contains("changed its codec")), + listener.warnings.toString()); + } + + @Test + void failedSegmentEndsRecording() throws Exception { + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("failed-%02d.mkv")) + .maxDuration(Duration.ofSeconds(1)) + .build(); + Listener listener = new Listener(); + + // The header of the second segment. + WriteFault.failHeader(1); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.addTrack(call.getAudioSender()); + recorder.start(); + + assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started"); + assertTrue(listener.failed.await(10, TimeUnit.SECONDS), "no error"); + + assertTrue(recorder.stop()); + assertEquals(MediaRecorderResult.PARTIAL, recorder.getResult()); + + List segments = recorder.getSegments(); + + // The first segment is whole, the second deleted. + assertEquals(1, segments.size(), segments.toString()); + assertEquals(MediaRecorderResult.COMPLETE, segments.get(0).getResult()); + assertPlaysOnItsOwn(segments.get(0).getFile(), 2); + + String error = listener.error.get(); + Path second = tempDir.resolve("failed-01.mkv"); + + assertTrue(error.startsWith("Writing the header of " + second), error); + + awaitTrue(() -> !Files.exists(second), () -> second + " not deleted"); + } + finally { + WriteFault.disarm(); + } + } + + @Test + void failedWriteKeepsPartialSegment() throws Exception { + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("partial-%02d.mkv")) + .maxDuration(Duration.ofSeconds(60)) + .build(); + Listener listener = new Listener(); + + WriteFault.failPacket(50); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.setListener(listener); + recorder.addTrack(call.getVideoSender()); + recorder.start(); + + assertTrue(listener.failed.await(10, TimeUnit.SECONDS), "no error"); + + assertTrue(recorder.stop()); + assertEquals(MediaRecorderResult.PARTIAL, recorder.getResult()); + + List segments = recorder.getSegments(); + + assertEquals(1, segments.size()); + assertEquals(MediaRecorderResult.PARTIAL, segments.get(0).getResult()); + assertTrue(Files.exists(segments.get(0).getFile())); + } + finally { + WriteFault.disarm(); + } + } + + @Test + void recordingWithoutMediaLeavesNoSegment(@TempDir Path dir) throws Exception { + SegmentOptions options = SegmentOptions.builder(dir.resolve("empty-%d.mkv")) + .maxDuration(Duration.ofSeconds(1)) + .build(); + + try (TestCall call = new TestCall(factory); + MediaRecorder recorder = new MediaRecorder(options)) { + recorder.addTrack(call.getVideoSender()); + recorder.start(); + + assertFalse(recorder.stop()); + assertEquals(MediaRecorderResult.EMPTY, recorder.getResult()); + assertTrue(recorder.getSegments().isEmpty()); + assertNull(recorder.getFile()); + } + + assertTrue(filesIn(dir).isEmpty(), filesIn(dir).toString()); + } + + @Test + void refusesMissingDirectory() { + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("missing").resolve("%d.mkv")) + .maxDuration(Duration.ofSeconds(1)) + .build(); + + assertThrows(NoSuchFileException.class, () -> new MediaRecorder(options)); + } + + @Test + void parsesPattern() { + SegmentOptions options = SegmentOptions.builder(tempDir.resolve("100%%-%04d.mkv")) + .maxSize(1) + .build(); + + assertEquals(4, options.width()); + assertEquals(".mkv", options.nameSuffix()); + assertEquals(tempDir.toAbsolutePath() + tempDir.getFileSystem().getSeparator() + "100%-", + options.pathPrefix()); + assertEquals(12, options.indexOf("100%-0012.mkv")); + assertEquals(12345, options.indexOf("100%-12345.mkv")); + assertEquals(-1, options.indexOf("100%-.mkv")); + assertEquals(-1, options.indexOf("100%-12a.mkv")); + assertEquals(-1, options.indexOf("100%-12.webm")); + + SegmentOptions plain = SegmentOptions.builder(tempDir.resolve("%d")).maxSize(1).build(); + + assertEquals(1, plain.width()); + assertEquals("", plain.nameSuffix()); + assertEquals(3, plain.indexOf("3")); + } + + @Test + void refusesBadPatterns() { + for (String name : new String[] { "call.mkv", "%d-%d.mkv", "%5d.mkv", "%s.mkv", "50%.mkv", "%019d.mkv", + "%0d.mkv" }) { + assertThrows(IllegalArgumentException.class, () -> SegmentOptions.builder(tempDir.resolve(name)), + name); + } + } + + @Test + void refusesBadLimits() { + SegmentOptions.Builder builder = SegmentOptions.builder(tempDir.resolve("%d.mkv")); + + assertThrows(IllegalStateException.class, builder::build); + assertThrows(IllegalArgumentException.class, () -> builder.maxDuration(Duration.ofMillis(999))); + assertThrows(IllegalArgumentException.class, () -> builder.maxSize(0)); + assertThrows(IllegalArgumentException.class, () -> builder.maxSegments(0)); + assertThrows(IllegalArgumentException.class, () -> builder.maxTotalSize(-1)); + } + + /** + * Checks that the file has the given number of streams, each of which + * begins at a key frame near the start of the file, as a segment that + * plays without the ones before must. + */ + static List assertPlaysOnItsOwn(Path file, int streams) throws IOException { + return assertPlaysOnItsOwn(file, streams, false); + } + + /** + * As {@link #assertPlaysOnItsOwn(Path, int)}, allowing streams without + * packets if asked to. + */ + static List assertPlaysOnItsOwn(Path file, int streams, boolean allowEmpty) + throws IOException { + List list = RecordingProbe.streamsOf(file); + + assertEquals(streams, list.size(), file + ": " + list); + + for (RecordingProbe.Stream stream : list) { + if (allowEmpty && stream.packets == 0) { + continue; + } + + assertTrue(stream.packets > 0, file + ": " + list); + + if (stream.video) { + assertTrue(stream.startsWithKeyFrame, file + ": " + list); + } + + // Every stream begins near zero, so the tracks stay in sync. + assertTrue(stream.firstPtsUs >= 0 && stream.firstPtsUs < 1_000_000, file + ": " + list); + } + + return list; + } + + /** + * Checks that a segment after the first begins with the key frame of a + * video track, which ended the segment before. + */ + static void assertBeginsWithVideo(Path file) throws IOException { + List list = RecordingProbe.streamsOf(file); + + assertTrue(list.stream().anyMatch(stream -> stream.video && stream.firstPtsUs < 50_000), + file + ": " + list); + } + + static MediaInfo readInfo(Path file) throws Exception { + try (MediaReader reader = new MediaReader(file)) { + return reader.getInfo(); + } + } + + static List filesIn(Path dir) { + try (Stream files = Files.list(dir)) { + return files.sorted().collect(Collectors.toList()); + } + catch (IOException e) { + throw new AssertionError(e); + } + } + + static void awaitTrue(BooleanSupplier condition, java.util.function.Supplier message) + throws InterruptedException { + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(10); + + while (!condition.getAsBoolean() && System.nanoTime() < deadline) { + Thread.sleep(20); + } + + assertTrue(condition.getAsBoolean(), message); + } + + + static class Listener implements MediaRecorderListener { + + final CountDownLatch started = new CountDownLatch(1); + + final List warnings = new CopyOnWriteArrayList<>(); + + final AtomicReference error = new AtomicReference<>(); + + final CountDownLatch failed = new CountDownLatch(1); + + final List segments = new CopyOnWriteArrayList<>(); + + + @Override + public void onStarted() { + started.countDown(); + } + + @Override + public void onWarning(String message) { + warnings.add(message); + } + + @Override + public void onError(String message) { + error.compareAndSet(null, message); + failed.countDown(); + } + + @Override + public void onSegmentFinished(MediaRecorderSegment segment) { + segments.add(segment); + } + + void awaitSegments(int count) throws InterruptedException { + awaitTrue(() -> segments.size() >= count, () -> "segments: " + segments); + } + } + +} diff --git a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java index e55116d21..5d321fd3f 100644 --- a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java +++ b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java @@ -69,6 +69,8 @@ class TestCall implements AutoCloseable { private final RTCRtpSender videoSender; private final RTCRtpSender audioSender; + private final PeerConnectionFactory factory; + private volatile boolean feeding; private Thread feeder; @@ -82,6 +84,8 @@ class TestCall implements AutoCloseable { * "PCMA". */ TestCall(PeerConnectionFactory factory, String audioCodec) throws Exception { + this.factory = factory; + caller = new Peer(factory); callee = new Peer(factory); @@ -120,6 +124,19 @@ RTCRtpSender getAudioSender() { return audioSender; } + /** + * Makes the caller send its video in the named codec from now on, by + * preferring it and negotiating the call again. + */ + void switchVideoCodec(String codecName) throws Exception { + prefer(factory, caller.connection, videoSender, MediaType.VIDEO, codecName); + + RTCSessionDescription offer = caller.createOffer(); + callee.setRemoteDescription(offer); + RTCSessionDescription answer = callee.createAnswer(); + caller.setRemoteDescription(answer); + } + /** * Returns the callee's receiver of the video (0) or audio (1) transceiver, * which follow the order of the offer. The instance is the caller's to diff --git a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/WriteFault.java b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/WriteFault.java index 5bf223b53..89e0c5567 100644 --- a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/WriteFault.java +++ b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/WriteFault.java @@ -50,7 +50,18 @@ private WriteFault() { /** * Fails the writing of the file header, before any media is in the file. */ - static native void failHeader(); + static void failHeader() { + failHeader(0); + } + + /** + * Fails the writing of the header that follows the given number of them, + * e.g. that of a later segment. + * + * @param afterHeaders How many headers are written before the one that + * fails. + */ + static native void failHeader(int afterHeaders); /** * Fails the write of the packet that follows the given number of them. From 8ab8d194fcbcd294082d48d11846026748b11bd1 Mon Sep 17 00:00:00 2001 From: Alex Andres Date: Mon, 9 Nov 2026 18:49:21 +0100 Subject: [PATCH 2/3] fix: drop key frame requests a rotation's key frame answered A request repeated while a rotation was due outlived the key frame that ended it, went out a second later, and held the next rotation's request back by up to a second, doubling segments on slow machines. --- .../main/cpp/include/media/MediaRecorder.h | 5 +++++ .../src/main/cpp/src/media/MediaRecorder.cpp | 19 +++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/webrtc-media/src/main/cpp/include/media/MediaRecorder.h b/webrtc-media/src/main/cpp/include/media/MediaRecorder.h index ecb1ba9a7..c284b912b 100644 --- a/webrtc-media/src/main/cpp/include/media/MediaRecorder.h +++ b/webrtc-media/src/main/cpp/include/media/MediaRecorder.h @@ -280,6 +280,11 @@ namespace ffmpeg // Asks every video track that is ready for a key frame. void RequestKeyFrames(); + // Forgets a key frame request of the track that the key frame it + // just sent answers, so that the request does not go out later, + // and hold up the next one that is needed. + void KeyFrameArrived(int track); + // Counts a frame that was dropped on the writer thread on the way // to its track's next key frame. void CountAwaitingKeyFrame(int track); diff --git a/webrtc-media/src/main/cpp/src/media/MediaRecorder.cpp b/webrtc-media/src/main/cpp/src/media/MediaRecorder.cpp index 832754f15..5a2717883 100644 --- a/webrtc-media/src/main/cpp/src/media/MediaRecorder.cpp +++ b/webrtc-media/src/main/cpp/src/media/MediaRecorder.cpp @@ -797,6 +797,12 @@ namespace ffmpeg Write(*output_, frame); } + // A request still held back from while the rotation was due is + // answered by this key frame. + if (video && frame.key_frame && switched_[index] && !rotation_due_) { + KeyFrameArrived(index); + } + if (!failed_ && !rotation_due_ && SegmentLimitReached()) { DueRotation(); } @@ -1010,6 +1016,19 @@ namespace ffmpeg } } + void MediaRecorder::KeyFrameArrived(int track) + { + std::lock_guard lock(mutex_); + + Input * input = inputs_[track].get(); + + // A track that waits for a key frame again, having dropped frames + // since this one was queued, still needs another. + if (!input->waiting_for_key_frame) { + input->key_frame_wanted = false; + } + } + void MediaRecorder::CountAwaitingKeyFrame(int track) { std::lock_guard lock(mutex_); From fd7e5cd737dcd6ce5a58697403e5ec3639d85544 Mon Sep 17 00:00:00 2001 From: Alex Andres Date: Mon, 9 Nov 2026 21:23:16 +0100 Subject: [PATCH 3/3] test: send no media while checking a segmented recording without any The call kept sending video, and a key frame arriving between start and stop put media into the recording on slow machines. --- .../webrtc/media/recorder/SegmentedRecorderTest.java | 2 ++ .../dev/onvoid/webrtc/media/recorder/TestCall.java | 11 +++++++++++ 2 files changed, 13 insertions(+) diff --git a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/SegmentedRecorderTest.java b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/SegmentedRecorderTest.java index 3654a2ea3..aa1aa4d52 100644 --- a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/SegmentedRecorderTest.java +++ b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/SegmentedRecorderTest.java @@ -481,6 +481,8 @@ void recordingWithoutMediaLeavesNoSegment(@TempDir Path dir) throws Exception { try (TestCall call = new TestCall(factory); MediaRecorder recorder = new MediaRecorder(options)) { + call.stopFeeding(); + recorder.addTrack(call.getVideoSender()); recorder.start(); diff --git a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java index 5d321fd3f..1129bc446 100644 --- a/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java +++ b/webrtc-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java @@ -124,6 +124,17 @@ RTCRtpSender getAudioSender() { return audioSender; } + /** + * Stops giving the caller media, and waits for what it has encoded to + * have been sent, so that its senders send nothing more. + */ + void stopFeeding() throws InterruptedException { + feeding = false; + feeder.join(); + + Thread.sleep(500); + } + /** * Makes the caller send its video in the named codec from now on, by * preferring it and negotiating the call again.