Merge pull request #1741 from naanlizard/rename-keyframeonlyifneed

Rename KeyframeOnlyIfNeed, update docs
AirenSoft · Nov 22, 2024 · 3274a9e · 3274a9e
2 parents d12b79a + f214627
commit 3274a9e
Show file tree

Hide file tree

Showing 4 changed files with 33 additions and 19 deletions.
diff --git a/docs/transcoding/README.md b/docs/transcoding/README.md
@@ -31,9 +31,8 @@ The `<OutputProfile>` setting allows incoming streams to be re-encoded via the `
 	Number of threads for the decoder.
 	<ThreadCount>2</ThreadCount>
 
-	To reduce resource usage, only keyframes are decoded.
-	It is only activated when image encoding and video bypass are enabled.
-	<KeyframeOnlyIfNeed>false</KeyframeOnlyIfNeed>
+	By default, OME decodes all video frames. If OnlyKeyframes is true, only the keyframes will be decoded, massively improving thumbnail performance at the cost of having less control over when exactly they are generated
+	<OnlyKeyframes>false</OnlyKeyframes>
     </Decodes>
     -->
 
@@ -341,26 +340,31 @@ The software decoder uses 2 threads by default. If the CPU speed is too low for
 
 ### Keyframe Decoding Only
 
-If only thumbnails are used without video encoding, decoding all frames wastes CPU resources. By decoding only keyframes for thumbnails, resource usage can be reduced. However, the frame rate of the output image may not be accurate.  Use the <**KeyFrameOnlyIfNeed>** option. Even if this value is set to true, if video encoding is enabled (Bypass is not included), all frames will be decoded.&#x20;
+For use cases without video (re)encoding, OME can be set to only decode the keyframes of incoming streams. This is a massive performance increase when all you are using the encoder for is generating thumbnails.
+
+To set OME to only decode keyframes, all of your encoder Output Profiles must be set to **<Bypass>true</Bypass>** set **<OnlyKeyframes>true</OnlyKeyframes>**. 
+
+Supported since OvenmediaEngine version 0.18.0 
 
 ```xml
 <OutputProfiles>
-    <!-- 
-    Common setting for decoders. Decodes is optional.
-    -->
-    <Decodes>
+<!-- Common setting for decoders. Decodes is optional. -->
+	<Decodes>
 	<!-- 
-	To reduce resource usage, only keyframes are decoded.
-	It is only activated when image encoding and video bypass are enabled. 
+	By default, OME decodes all video frames. 
+	With OnlyKeyframes, only keyframes are decoded,
+	massively improving performance.
+	Thumbnails are generated only on keyframes,
+	they may not generate at your requested fps!
 	-->
-        <KeyframeOnlyIfNeed>false</KeyframeOnlyIfNeed>
-    </Decodes>
+		<OnlyKeyframes>true</OnlyKeyframes>
+	</Decodes>
 
     <OutputProfile>
        <Encodes>
            <Video>
                 <Bypass>true</Bypass>	
-  	   </Video>
+  		   </Video>
            <Image>
                <Codec>jpeg</Codec>
                <Width>1280</Width>

diff --git a/misc/conf_examples/Server.xml b/misc/conf_examples/Server.xml
@@ -309,7 +309,17 @@
 					<!-- Application type (live/vod) -->
 					<Type>live</Type>
 					<OutputProfiles>
-
+					<!-- Common setting for decoders. Decodes is optional. -->
+						<Decodes>
+						<!-- 
+						By default, OME decodes all video frames. 
+						With OnlyKeyframes, only keyframes are decoded,
+						massively improving performance.
+						Thumbnails are generated only on keyframes,
+						they may not generate at your requested fps!
+						-->
+							<OnlyKeyframes>true</OnlyKeyframes>
+						</Decodes>
 						<!-- 
 						Common setting for decoders. Decodes is optional.
 
@@ -319,7 +329,7 @@
 
 							To reduce resource usage, only keyframes are decoded.
 							It is only activated when image encoding and video bypass are enabled.
-							<KeyframeOnlyIfNeed>false</KeyframeOnlyIfNeed>
+							<OnlyKeyframes>false</OnlyKeyframes>
 						</Decodes>
 						-->
 

diff --git a/src/projects/config/items/virtual_hosts/applications/output_profiles/decodes/decodes.h b/src/projects/config/items/virtual_hosts/applications/output_profiles/decodes/decodes.h
@@ -21,17 +21,17 @@ namespace cfg
 				public:
 					// Informal Option 
 					CFG_DECLARE_CONST_REF_GETTER_OF(GetThreadCount, _thread_count);
-					CFG_DECLARE_CONST_REF_GETTER_OF(IsKeyframeOnlyIfNeed, _keyframe_only_if_need);
+					CFG_DECLARE_CONST_REF_GETTER_OF(IsOnlyKeyframes, _only_keyframes);
 
 				protected:
 					void MakeList() override
 					{
 						Register<Optional>("ThreadCount", &_thread_count);
-						Register<Optional>("KeyframeOnlyIfNeed", &_keyframe_only_if_need);
+						Register<Optional>("OnlyKeyframes", &_only_keyframes);
 					}
 
 					int32_t _thread_count = 2;
-					bool _keyframe_only_if_need = false;
+					bool _only_keyframes = false;
 				};
 			}  // namespace dec
 		}	   // namespace app

diff --git a/src/projects/transcoder/transcoder_stream.cpp b/src/projects/transcoder/transcoder_stream.cpp
@@ -799,7 +799,7 @@ bool TranscoderStream::CreateDecoder(MediaTrackId decoder_id, std::shared_ptr<in
 
 	// Set the keyframe decode only flag for the decoder.
 	if (input_track->GetMediaType() == cmn::MediaType::Video &&
-		GetOutputProfilesCfg()->GetDecodes().IsKeyframeOnlyIfNeed() == true)
+		GetOutputProfilesCfg()->GetDecodes().IsOnlyKeyframes() == true)
 	{
 		input_track->SetKeyframeDecodeOnly(IsKeyframeOnlyDecodable(_output_streams));
 	}