Automatic File Splitting

[dodgepong]

Automatic File Splitting

THIS BOUNTY HAS BEEN COMPLETED! 🎉

Commit: 0e81c66

Feature Summary

Allow users to choose to save recordings in split files instead of one monolithic file.

Background and Motivation

When recording video files in OBS Studio, files are saved as a single video file. This makes sense in the general case, but there are some situations where having one single file is awkward. For example:

• If a video is long and recording at very high quality, the file size could be unwieldy to work with, especially in a video editor. File operations could take a long time when being applied to an overly-large video file.
• Many users feel a peace-of-mind about recordings that have been split and are finalized in context of taking efforts to prevent a file from being corrupted for some reason. While recording to FLV/MKV can prevent issues or video file corruption in the event of an OBS crash, that file format is not often easy to work with, given the necessesity of the extra remux step. Splitting files would allow users to record directly in MP4 with measures taken to combat file corruption.
• While streaming and recording a live event, it can be useful to start transferring and working with the recorded version of the stream before the stream ends for archival purposes. The streamer could stop and restart the recording, but it's convenient to not need to touch OBS in order to access recording files that have already been closed are are not being written to.

Request For Proposal

Submit a proposal explaining how you will implement this feature such that it meets the following requirements:

• Add a feature to OBS recording settings to automatically split files according to user-specified criteria
  • Users should have the ability to select whether the file should be split after a certain amount of time (e.g. 20 minutes), or when a file reaches a certain file size (e.g. 4 GB).
  • Split files should play back seamlessly when stitched back together using a video editor, or a tool like FFmpeg. There should be no skipped frames or skipped audio.
  • The feature should be disabled by default.
  • File formats that require finalization should finalize invisibly in the background and should not interrupt the OBS UI when the file is split.
  • The feature should work on Windows, macOS, and Linux.*

* Multiple contributors may assist with implementation on different platforms and may split the bounty according to the level of contribution they made to the project.

Please read Tips for Writing a Good Proposal for guidance on how to author your proposal.

The OBS development team will consider all submitted proposals and select one submission to be implemented by the developer who submitted it. That developer will be eligible to collect the bounty upon completion of the project according to the criteria listed below.

Bounty

The bounty for implementing this feature is $1500.

You can learn more about the OBS Project Bounty Program here.

If you wish to contribute funds toward increasing the amount on this bounty, contribute to the OBS Project Bounty Fund and select the "Automatic File Splitting" option (or just click here).

Completion Criteria

You may collect the bounty when the following are true:

• Your proposal addresses all items listed in the "Request For Proposal" section.
• You have submitted one more more pull requests that fully implement the feature as you proposed.
• Your pull request(s) are reviewed, and you have responded to review comments within a reasonable time frame.
• Your pull request(s) are merged into the master branch of the appropriate obsproject repositories.

Additional Information

Related idea from the OBS Ideas Page:

• https://ideas.obsproject.com/posts/111/add-a-split-file-feature

Related posts on the OBS Forums:

• https://obsproject.com/forum/threads/automatic-split-output-files.73788/
• https://obsproject.com/forum/threads/file-split-after-size.43707/

[norihiro]

I'd like to make a proposal for Automatic File Splitting.

Proposal of implementation

This proposal mainly changes a backend built-in plugin ffmpeg_output.
Just small changes will be made to UI and file name generation code.

Backend (ffmpeg-mux)

This is the main part of the implementation. The plugin plugins/obs-ffmpeg/obs-ffmpeg-mux.c is the output file multiplexer for Simple output mode and Advanced output mode with Standard type (not Custom output (FFmpeg)). This output plugin calls a subprocess implemented in plugins/obs-ffmpeg/ffmpeg-mux/ffmpeg-mux.c. In the ffmpeg-mux.c, an output format segment is added as a primary format.

obs-studio/plugins/obs-ffmpeg/ffmpeg-mux/ffmpeg-mux.c

Lines 656 to 659 in cd5873e

	if (is_network && !is_http)
	output_format = av_guess_format("mpegts", NULL, "video/M2PT");
	else
	output_format = av_guess_format(NULL, ffm->params.file, NULL);

Suggestion:

        if (is_network && !is_http)
                output_format = av_guess_format("mpegts", NULL, "video/M2PT");
        else if (is_segment)
                output_format = av_guess_format("segment", ffm->params.file, NULL);
        else
                output_format = av_guess_format(NULL, ffm->params.file, NULL);

When passing muxer_settings to the actual output-format, it will set to segment_format_options.
Some segment settings will be also set here.

obs-studio/plugins/obs-ffmpeg/ffmpeg-mux/ffmpeg-mux.c

Lines 594 to 595 in cd5873e

	AVDictionary *dict = NULL;
	if ((ret = av_dict_parse_string(&dict, ffm->params.muxer_settings, "=",

Suggestion:

        AVDictionary *dict = NULL;
        if (is_segment) {
                av_dict_set(&dict, "segment_format_options", ffm->params.muxer_settings, 0);
                av_dict_set_int(&dict, "segment_time", segment_time, 0);
                // TODO: and other parameters if necessary.
        }
        else if ((ret = av_dict_parse_string(&dict, ffm->params.muxer_settings, "=",

Backend (ffmpeg-output)

According to the feedback from Jim, the change in ffmpeg-output might not be necessary depending on what output(s) to be supported.
The plugin plugins/obs-ffmpeg/obs-ffmpeg-output.c is currently processing output format using FFmpeg.
A segment output format will be added here.

Create a segment format instead.

obs-studio/plugins/obs-ffmpeg/obs-ffmpeg-output.c

Lines 573 to 575 in 725fce7

	AVOutputFormat *output_format = av_guess_format(
	is_rtmp ? "flv" : data->config.format_name, data->config.url,
	is_rtmp ? NULL : data->config.format_mime_type);

Suggestion:

        AVOutputFormat *output_format = av_guess_format(
                is_segment ? "segment" :
                is_rtmp ? "flv" : data->config.format_name, data->config.url,
                is_rtmp ? NULL : data->config.format_mime_type);

The format information will be passed through a segment_format option.
The actual format will be processed by the segment format internally.

obs-studio/plugins/obs-ffmpeg/obs-ffmpeg-output.c

Lines 398 to 407 in 725fce7

	AVDictionary *dict = NULL;
	if ((ret = av_dict_parse_string(&dict, data->config.muxer_settings, "=",
	" ", 0))) {
	ffmpeg_log_error(LOG_WARNING, data,
	"Failed to parse muxer settings: %s\n%s",
	av_err2str(ret), data->config.muxer_settings);
	av_dict_free(&dict);
	return false;
	}

Suggestion:

        AVDictionary *dict = NULL;
        if (is_segment) {
                av_dict_set(&dict, "segment_format", data->config.format_name, 0);
                av_dict_set(&dict, "segment_format_options", data->config.muxer_settings, 0);
                // TODO: set some other options such as `segment_time`
        }
        else if ((ret = av_dict_parse_string(&dict, data->config.muxer_settings, "=",
                                        " ", 0))) {
                ffmpeg_log_error(LOG_WARNING, data,
                                 "Failed to parse muxer settings: %s\n%s",
                                 av_err2str(ret), data->config.muxer_settings);

                av_dict_free(&dict);
                return false;
        }

Configuration and data structure

Need to implement two data structures;

• obs_data_t *settings for the ffmpeg_output:
  This is an internal data that is generated when starting the output.
• main->Config(), section AdvOut:
  This is the primary place to hold the settings for segment.

In addition to the new settings, also need to consider url holds the format string for segment.

UI

The settings will be implemented into Settings/Output/Recording tab for both Standard and Advanced output modes.

These settings will be added

• Check box to enable Automatic File Splitting
• Combobox to select by time or by size (automatically hidden by Automatic File Splitting)
• Numerical input box to set Time to split in seconds or maybe minutes (if by time is selected)
• Numerical input box to set Size to split in megabytes (if by time is selected)

Optionally, add some settings as below. Suggestion is welcome.

• Create file list
• Reset timestamps
  The defacto-standard in camcorders looks not to reset. However, compatibility is better to reset.

File name

Currently the file name is generated by os_generate_formatted_filename in libobs/util.
The fine name gneration might be moved into segment format. There are two ways to name the files.

• YYYY-MM-DD HH:MM:SS-%d.mkv where %d is the index of the segment. The time will express the start time of the first segmented file.
  In this case, os_generate_formatted_filename need to return a file name with -%d.
• YYYY-MM-DD HH:MM:SS.mkv with the start time of each segmented file.
  In this case, os_generate_formatted_filename won't be called but pass strftime format to the segment format. Need to ensure strftime is enabled when building FFmpeg.

Considerations between other features

• Custom URL:
  If the output is stream such as RTMP, RTMPS, or HLS, the segment feature should be disabled silently. Otherwise, meaning the output is regular file(s), the URL has to contain the format string (%d, etc.) so that the segment format can rename according to the provided URL.
• Remux:
  When remuxing, the video files will be concat automatically into a single file. For this purpose, segment_list file in ffconcat type will be generated.
• Replay Buffer:
  I need to see the new feature does not break the replay buffer feature. The replay buffer looks saving to different files so that it won't be impacted without further attentions.

Satisfaction of the requirements

Requirements

• Users should have the ability to select whether the file should be split after a certain amount of time (e.g. 20 minutes), or when a file reaches a certain file size (e.g. 4 GB).
  • Ability to split by the time is achieved by above change.
  • Ability to split by the file size requires further implementation to be discussed in Open issues section below.
• Split files should play back seamlessly when stitched back together using a video editor, or a tool like FFmpeg. There should be no skipped frames or skipped audio.
  • There is no skipped frames or skipped audio.
    The video will be splitted at the key frame so that user can stitched back without any loss.
• The feature should be disabled by default.
• File formats that require finalization should finalize invisibly in the background and should not interrupt the OBS UI when the file is split.
  • The UI won't be interrupted since the process is done in the backend.
• The feature should work on Windows, macOS, and Linux.

Pros

• I think this is relatively simple solution because just using the existing segment format from FFmpeg.
  (I tried above change in the backend with hard coded is_segment and url, confirmed segmented output file is generated.)

Open issues

• FFmpeg's segment format does not have a feature to split by file size.
  Possible solutions will be
  • Convert the bitrate in configuration and size limit to the segment_time option of the segment format.
    This is a simple implementation but I think inaccurate and it could generate files exceeding the limited size.
  • Modify libavformat to support segmenting by size.
    This is a straightforward way and beneficial for not only OBS community but also FFmpeg users. However, it is out of OBS community's control to change FFmpeg's code. We need to change libavformat/segment.c in FFmpeg. For Windows and macOS, we can apply a patch since the avformat DLL and dylib are bundled. For Ubuntu, we need to wait until FFmpeg project accept the feature and Ubuntu include the new version of FFmpeg.
  • Implement from scratch as same as segment format in obs-studio repo.
    This idea should be made as another proposal.
  • Won't implement the segment-by-size option.
    Simplicity of the code is also important. I think it's worth to consider dropping the feature to segment by size.
• The segment point depends on the timing of a keyframe (I-frame).
  If accurate timing of the segment is required, the keyframe timing should be controlled. I think it should be documented to set the keyframe interval. Or, should we internally control the keyframe interval?

Time estimation

It will take roughly 1-2 weeks including implementation and some debugging but excluding the segment-by-size option. It may vary depending on my other activities.

Comment

This proposal addresses the feature to split the file by the time. However the other feature to split by the size is also considered, I think it is a reasonable choice not to implement the "split by the size" feature for now in terms of the simplicity and maintainability of the OBS Studio's code. Possible solutions and workarounds are discussed above.

[dodgepong]

I agree that we should favor cutting at a keyframe interval rather than strictly adhering to a requested file size. My guess is that the most practical way to do this is to cut at the first segment that puts the file size over the limit, so files will technically be slightly larger than requested.

[norihiro]

does using the FFmpeg "segment" feature cause it to segment on keyframe boundaries?

Yes, the segment output format will segment at the boundary of GOP (group of picture). So, basically, it will split the beginning of keyframe. All frames can be decoded without referring previous/next file.

I'm asking because I want to make sure it doesn't internally make FFmpeg to reencode or something, which would be bad.

No, it never re-encode the codec. The segment format is just a multiplexer. It is just split frames and send to the real format (FLV, matroska, etc.).
I agree it's bad in terms of it consumes CPU or HW resource.

You seemed to mention keyframe intervals but I'm not sure if that's something that you've confirmed yet.

What I'm considering is a situation like this.
The key frame inteval is set to 7 seconds, for example, but the file splitting is requested at 5 minutes. Then, it will exceed 6 seconds since 5 minutes (300 seconds) is not a multiple of 7 seconds.
Similar discussion will be applicable if user didn't set the keyframe interval. In that case, the keyframe will be inserted depending on the encoder. I saw x264 made a keyframe in around 30 seconds. I thought it's relatively long.

it's not a big deal if the keyframe interval is large.

I agree that. The output file is slightly larger than the requested time. The data won't be broken.

It'd be preferable to use the keyframe before the cutoff point but that might be more difficult than the keyframe after. Not sure.

Your understanding is correct.
In the proposed method, it will split at the first keyframe after reaching the specified time.
To split before the cutoff point, I think we need to store all the non-keyframe until the next keyframe reaches. It's not possible just using the FFmpeg's segment output format. We need to implement from scratch. In that case, since all stored non-keyframes are output at once, I'm afraid performance might be periodically impacted.

[jp9000]

Sorry it's taken a while to get back to you.

For your open issues, modifying libavformat is a no-go for sure.

Honestly, if I were to implement this, I would probably just have a size counter or a duration counter, and when that size/duration counter reaches the set limit, I'd manually restart the output seamlessly at the next available I-frame. Basically I wouldn't use FFmpeg to do the splitting at all if it doesn't support the features. From my experience working with video/audio frames like this, I don't think this feature is very complex to write from scratch manually.

If FFmpeg isn't cutting it, would you be willing to write splitting manually perhaps, @norihiro? If needed I can help give guidance on it. It's not as bad as it sounds. Hardest part would mostly just be getting avformat to restart for a new file. I can show you how to examine frame data to check for i-frames and such if needed, it's fairly trivial.

Oh, and another thing that might be annoying are the audio packets; audio packets will not be guaranteed to be in synchronization for every subsequent split file. You'd probably have to allow some very minor desync on audio playback on subsequent split files in order to do it properly. Audio packets are typically 1024 frames, which at 44100hz is approximately ~23 milliseconds, so no matter what audio frames might be off within that threshold. I think that should be fine, but just something to be aware of.

[norihiro]

Thank you for your reply.

If FFmpeg isn't cutting it, would you be willing to write splitting manually perhaps, @norihiro? If needed I can help give guidance on it. It's not as bad as it sounds.

The code of splitting by the time is there in FFmpeg. It should be not difficult for me to re-implement the similar thing in the plugin before sending to FFmpeg's multiplexer.
So, what we want to implement is not using segment filter of FFmpeg but to implement it by ourselves.

Audio packets are typically 1024 frames, which at 44100hz is approximately ~23 milliseconds, so no matter what audio frames might be off within that threshold.

I have previously calculated that for 48kHz case, which will be ~21ms, and identified it's negligibly small. I should have commented about that. There would be more concern on MP3 but I don't think people uses such codecs. Maybe the player side can adjust the timing based on the timestamps.

[jp9000]

So, what we want to implement is not using segment filter of FFmpeg but to implement it by ourselves.

Yea, exactly, if FFmpeg doesn't have the capability we want, then we should probably just implement it ourselves. It's not as hard as it sounds. I implemented the ability to pause recordings which would be designed very similarly to this feature, so from my experience it's not a difficult task.

[norihiro]

This is another proposal to implement in obs-ffmpeg-mux plugin as dicussed in the other comment thread.

Basic Concept of Splitting the Stream

The proposal suggest to follow the implementation of the segment muxer in FFmpeg. Once it reaches the splitting timing and the next frame is a key frame, the muxer just closes its internal muxer and then starts a new muxer.

libavformat/segment.c line 904-908

        if ((ret = segment_end(s, seg->individual_header_trailer, 0)) < 0)
            goto fail;

        if ((ret = segment_start(s, seg->individual_header_trailer)) < 0)
            goto fail;

The splitting timing is controlled by the video stream. Since the packets of video and audio have already been ordered, we don't need to hold both previous and new files for audio when splitting but just switch to the new file.

Unfortunately, the segment avformat does not have the ability to split by time, we will re-implement similar algorithm in obs-ffmpeg-mux.

Implementation in the Plugin

API of the Plugin

Add new settings (same as that for replay_buffer)

• Split settings
  • max_time_sec (int): Set 0 to disable, positive integer to split by by time in specified value in second.
  • max_size_mb (int): Set 0 to disable, positive integer to split by by size in specified value in mega-byte.
• File name settings
  • directory (string)
  • format (string)
  • extension (string)
  • allow_spaces (bool)
  • allow_overwrite (bool)
• Some other optional settings such as making file list, reset PTS.

Above settings subject to change.

File name generation

File names for the 2nd and later files will be generated in the output plugin ffmpeg_muxer to avoid interacting with UI. The first file name will be still generated in UI as same as current implementation. This is also required to pass the directory of the file to the remuxer. Necessary information to generate the file name is passed through the settings of the plugin. The same function as BasicOutputHandler::GetRecordingFilename will be implemented in the plugin. Will reuse file name generation in replay_buffer_save.

UI

The settings will be implemented into Settings/Output/Recording tab for both Standard and Advanced output modes.

Backend

Source file: plugins/obs-ffmpeg/obs-ffmpeg-mux.c
Function: write_packet

Call os_process_pipe_destroy and start_pipe

Pros:

• Don't need to pass file name format to the subprocess.
• The subprocess won't be touched so that the functionality of the subprocess is minimal.

Cons:

• Overhead of creating a new subprocess might cause missing frame or something especially on old machine with Windows.
• Replay Buffer, HLS:
  Some code in obs-ffmpeg-mux.c is shared for Replay Buffer and HLS. Need cautions especially non-static functions.

If overhead of the subprocess creation matters, I will consider this idea.
Send the new file name to the subprocess ffmpeg-mux.
In the subprocess, call ffmpeg_mux_free and ffmpeg_mux_init when received the new file name.

Other Considerations

• Remux:
  Optionally, we could add a feature for remuxing to automatically concat into a single file. For this purpose, ffconcat file should be generated.
• Starting PTS for each file:
  Some video editors might not be able to handle video files that starts non-zero PTS. For that editors, we should provide an option to reset PTS for each video. In this case, need to be careful how to handle audio's PTS (still we will follow the implementation of Fmpeg's segment mux).

Completion Criteria

• Users should have the ability to select whether the file should be split after a certain amount of time (e.g. 20 minutes), or when a file reaches a certain file size (e.g. 4 GB).
  • After exceeding the specified time or size, the file will be splitted at the first keyframe.
  • The file size will be judged by the total size of encoded video and audio. Mux overhead (header of MP4, etc.) is ignored. The generated files will technically be slightly larger than requested.
• Split files should play back seamlessly when stitched back together using a video editor, or a tool like FFmpeg. There should be no skipped frames or skipped audio.
  • I will follow the segment implementation in FFmpeg. I tested segment and stitched back by concat. There is no difference in audio.
• The feature should be disabled by default.
• File formats that require finalization should finalize invisibly in the background and should not interrupt the OBS UI when the file is split.
• The feature should work on Windows, macOS, and Linux.

[jp9000]

Alrighty then, that sounds good to me. If you'd like to take on this task then I'll approve your proposal.

[norihiro]

Yes, I'd like to take this implementation.

[WizardCM]

@norihiro Excellent. I've marked this bounty as "In Progress" and you can start as soon as you're able. If you're not already on the OBS Discord, I highly recommend it for any questions you may have when building/developing.

[p10tyr]

This feature would be great. Another use case is for unstable internet.. where maybe you have good upload but latency fluctuations make live streaming really unstable. Then a person can just upload the files to a remote server in its container, remux it remotely and stream from there.

I seriously thought this would be in OBS as it seems such a standard option every else.. I am quite surprised that I can't do this.. and now I'm stuck with a laggy stream.. cause you know the internet isn't perfect everywhere.

Just reading other criteria.. yes please make sure to to prove PTS in each file because this is a massive problem with gstreamer if it doesn't exists. I had to pre process files to add this info which causes more delays

[Fenrirthviti]

Please refrain from off-topic comments not directly related to the discussion of the bounty itself, or an implementation. Thanks for your understanding. This comment will now be deleted.

[p10tyr]

I was looking for this feature to do some custom streaming because I have issues with internet so I need to basically do HLS file uploads manually...

And it struck me, this "feature" can already be done!

Just go to Recording and set m3u8 Format.
The keyframe interval is how many seconds apart the file will be split and this is crucial as you can play back each file separately since it contains the PTS data.

For my use case this ideal because I can just upload the files as fast as I can and remux them else where for streaming.

For the proposed solutions.. I would not use a key frame longer than 10 seconds because any data corruption within that segment will cause artefacts.

The proposal is the be able to almost.. group these files , or remux them locally to desired lengths, maybe 10 minute segments that contain 2 second key intervals.

Just food for thought..

[Fenrirthviti]

This feature has already been completed and will be in OBS 28.