Ogg: Difference between revisions

From GiderosMobile
No edit summary
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
<!-- GIDEROSOBJ:Ogg -->
<!-- GIDEROSOBJ:Ogg -->
'''Supported platforms:''' [[File:Platform android.png]][[File:Platform ios.png]][[File:Platform mac.png]][[File:Platform pc.png]]<br/>
'''Supported platforms:''' [[File:Platform android.png]][[File:Platform ios.png]][[File:Platform mac.png]][[File:Platform pc.png]][[File:Platform winrt.png]][[File:Platform win32.png]]<br/>
'''Available since:''' Gideros 2017.10<br/>
'''Available since:''' Gideros 2017.10<br/>
'''TODO: rename this wiki page to Theora? plus add missing functions ''theora.beginVideo'', ''theora.encodeVideoFrame'''''


=== Description ===
=== Description ===
Adds support for Ogg audio and video (Theora).
Adds support for Ogg audio and video (Theora) to Gideros.


There are two ways to use the Ogg plugin:
There are two ways to use the Ogg plugin:
* to read Ogg files use:
*to read Ogg files use:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local theora = require "Theora"
local theora = require "Theora"
</syntaxhighlight>
</syntaxhighlight>
* to encode/decode Ogg files use:
*to encode/decode Ogg files use:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
-- Theora system
-- Theora system
local theora = require "theora.core"
local theora = require "theora.core"
</syntaxhighlight>
</syntaxhighlight>
Enable Ogg in Gideros Studio -> Plugins before use.
==== Theora ====
<del>Theora is a subclass of Sound, so every Sound and SoundChannel method also works on a Theora object and on the channel it returns. Because the plugin also registers an Ogg decoder with the sound system, plain Ogg Vorbis audio files can simply be loaded with Theora.new() as well</del>.
One Ogg file may contain an Ogg Vorbis audio stream, an Ogg Theora video stream, or both of them together. Theora:play() starts the sound part and Theora:getVideo() displays the video part.
==== Theora.core ====
The theora.core table gives direct access to the Ogg streams behind a sound channel. Its functions raise a Lua error when the stream id is invalid, so they should be called inside pcall when the input is not guaranteed.
=== Notes ===
*The encoder only accepts frame sizes that are multiples of 16, so round width and height up before creating the RenderTarget
*Image format 3 (YUV420) is the only format supported by the encoder at the moment
*The video is decoded on the CPU and uploaded to textures, so large videos are expensive on low end devices; prefer sizes close to what is really displayed
*Theora:play() creates new textures for every playback, so stop the channel instead of keeping many channels alive
*theora.core functions throw Lua errors on invalid stream ids; use pcall if the stream may not exist
*Video frames are drawn by the plugin renderer when their timestamp is due, which keeps them in step with the audio stream of the same file


=== Examples ===
=== Examples ===
Line 120: Line 136:
[[Theora.new]] ''creates a new Ogg/Theora object''<br/><!--GIDEROSMTD:Theora.new(path) creates a new Ogg/Theora object-->
[[Theora.new]] ''creates a new Ogg/Theora object''<br/><!--GIDEROSMTD:Theora.new(path) creates a new Ogg/Theora object-->
[[Theora:getVideo]] ''reads video from an Ogg/Theora stream object''<br/><!--GIDEROSMTD:Theora:getVideo() reads video from an Ogg/Theora stream object-->
[[Theora:getVideo]] ''reads video from an Ogg/Theora stream object''<br/><!--GIDEROSMTD:Theora:getVideo() reads video from an Ogg/Theora stream object-->
[[Theora:play]] ''creates a new Ogg/Theora stream object''<br/><!--GIDEROSMTD:Theora:play() creates a new Ogg/Theora stream object-->
[[Theora:play]] ''creates a new Ogg/Theora stream object''<br/><!--GIDEROSMTD:Theora:play(startTime, looping, paused) creates a new Ogg/Theora stream object-->
 
[[theora.core.beginVideo]] ''starts the video encoder of an encoding (recording) stream''<br/><!--GIDEROSMTD:theora.core.beginVideo(streamId, codec, frameRate, width, height, format, quality) starts the video encoder of an encoding (recording) stream-->
[[theora.core.encodeVideoFrame]] ''encodes one video frame taken from a render target and writes it into the recording file''<br/><!--GIDEROSMTD:theora.core.encodeVideoFrame(streamId, framePosition, renderTarget, endOfStream) encodes one video frame taken from a render target and writes it into the recording file-->
[[theora.core.getVideoInfo]] ''reads the properties of the video stream attached to a channel''<br/><!--GIDEROSMTD:theora.core.getVideoInfo(streamId) reads the properties of the video stream attached to a channel-->
[[theora.core.setVideoSurface]] ''attaches the textures that receive the decoded Y, U and V planes of a video stream''<br/><!--GIDEROSMTD:theora.core.setVideoSurface(streamId, yTexture, uTexture, vTexture) attaches the textures that receive the decoded Y, U and V planes of a video stream-->


| style="width: 50%; vertical-align:top;"|
| style="width: 50%; vertical-align:top;"|
=== Events ===
=== Events ===
<!--[[Event.COMPLETE]]<br/>-->
[[Theora_Event.COMPLETE]]<br/><!--GIDEROSEVT:Event.COMPLETE complete-->
=== Constants ===
=== Constants ===
|}
|}


{{GIDEROS IMPORTANT LINKS}}
{{GIDEROS IMPORTANT LINKS}}

Latest revision as of 00:38, 14 November 2026

Supported platforms:
Available since: Gideros 2017.10

Description

Adds support for Ogg audio and video (Theora) to Gideros.

There are two ways to use the Ogg plugin:

  • to read Ogg files use:
local theora = require "Theora"
  • to encode/decode Ogg files use:
-- Theora system
local theora = require "theora.core"

Enable Ogg in Gideros Studio -> Plugins before use.

Theora

Theora is a subclass of Sound, so every Sound and SoundChannel method also works on a Theora object and on the channel it returns. Because the plugin also registers an Ogg decoder with the sound system, plain Ogg Vorbis audio files can simply be loaded with Theora.new() as well.

One Ogg file may contain an Ogg Vorbis audio stream, an Ogg Theora video stream, or both of them together. Theora:play() starts the sound part and Theora:getVideo() displays the video part.

Theora.core

The theora.core table gives direct access to the Ogg streams behind a sound channel. Its functions raise a Lua error when the stream id is invalid, so they should be called inside pcall when the input is not guaranteed.

Notes

  • The encoder only accepts frame sizes that are multiples of 16, so round width and height up before creating the RenderTarget
  • Image format 3 (YUV420) is the only format supported by the encoder at the moment
  • The video is decoded on the CPU and uploaded to textures, so large videos are expensive on low end devices; prefer sizes close to what is really displayed
  • Theora:play() creates new textures for every playback, so stop the channel instead of keeping many channels alive
  • theora.core functions throw Lua errors on invalid stream ids; use pcall if the stream may not exist
  • Video frames are drawn by the plugin renderer when their timestamp is due, which keeps them in step with the audio stream of the same file

Examples

Recording your mic and camera to an .ogg video file

-- Microphone plugin, for recording in gideros
require "microphone"
-- Camera plugin, to get images from
require "camera"
-- Theora system (from ogg plugin)
local theora = require "theora.core"

--Locate available cameras
lst=Camera.availableDevices()
for k,cam in ipairs(lst) do
	print("#"..k.." Desc:"..cam.description.." Pos:"..cam.position.." Dev:"..cam.name)
end
-- Pick the first available
local cname=lst[1].name

cw,ch=640,480
--Theora needs full 16x16 blocks
ch=(ch+15)&~15
cw=(cw+15)&~15
--Create texture and start camera
Camera.texture=RenderTarget.new(cw,ch)
Camera.start(Camera.texture,cname)

--Set our stage size
application:setLogicalDimensions(cw,ch)
--Show our live video
local b=Bitmap.new(Camera.texture)
stage:addChild(b)

--Prepare for recording
local mic=Microphone.new("",24000,2,16)
mic:setOutputFile("|T|mic.ogg")

--Launch recording process
Core.asyncCall(function()
	--Wait a frame and disable auto yield
	Core.yield(true)
	--Start recording and get recording stream id
	mic:start()
	local id=mic:getStreamId()
	--Encode video header immediately, before audio data gets encoded
	--Parameters are:
	-- stream id, codec name, frame rate, image width, image height,
	-- image format (use 3 for now, nothing else is supported), image quality
	theora.beginVideo(id,"theora",30,cw,ch,3,0.6)
	-- Now encode 120 video frames, every other gideros frame (60fps->30fps)
	for i=1,120 do
		--Parameters:
		-- stream id, frame id (zero based), image texture, end of stream indicator
		theora.encodeVideoFrame(id,(i-1),Camera.texture,(i==120))
		Core.yield(true)
		Core.yield(true)
	end
	-- Stop recording
	mic:stop()
	-- For testing, read encoded file and print its size
	local f=io.open("|T|mic.ogg","rb")
	local ct=f:read("*all")
	f:close()
	print("Ended",#ct) 
end)

Example 2

local theora = require "theora.core"
require "microphone"
 
local texw, texh = 120*16, 68*16
local tex = RenderTarget.new(texw, texh)
local dot = Pixel.new(0xFF0000, 16, 16)
dot:setAnchorPoint(.5,.5)

local microphone = Microphone.new(8000, 1, 16)
microphone:setOutputFile("|D|test.ogg")

Core.asyncCall(function()
	microphone:start()
	theora.beginVideo(microphone:getStreamId(),"theora",30,texw,texh,3,0.6)

	for i = 1, 360, 2 do
		tex:clear(0x303030)
		tex:draw(dot, math.cos(^<i)*texh*.4+texw/2, math.sin(^<i)*texh*.4+texh/2)
		theora.encodeVideoFrame(microphone:getStreamId(), (i-1), tex, (i==360))
	end

	microphone:stop()
	print("Finished")

end)

Methods

Theora.new creates a new Ogg/Theora object
Theora:getVideo reads video from an Ogg/Theora stream object
Theora:play creates a new Ogg/Theora stream object

theora.core.beginVideo starts the video encoder of an encoding (recording) stream
theora.core.encodeVideoFrame encodes one video frame taken from a render target and writes it into the recording file
theora.core.getVideoInfo reads the properties of the video stream attached to a channel
theora.core.setVideoSurface attaches the textures that receive the decoded Y, U and V planes of a video stream

Events

Theora_Event.COMPLETE

Constants