Ogg: Difference between revisions
No edit summary |
No edit summary |
||
| (2 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/> | ||
=== 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)
MethodsTheora.new creates a new Ogg/Theora object theora.core.beginVideo starts the video encoder of an encoding (recording) stream |
EventsConstants |