Metadata-Version: 2.1
Name: ogre-oggsound
Version: 14.6.2
Summary: OgreOggSound audio bindings for ogre-python
Author: Ian Stangoe
Maintainer: Pavel Rojtberg
License: Copyright (c) 2008-2010, Kresimir Spes (kreso@cateia.com)
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
             * Redistributions of source code must retain the above copyright
               notice, this list of conditions and the following disclaimer.
             * Redistributions in binary form must reproduce the above copyright
               notice, this list of conditions and the following disclaimer in the
               documentation and/or other materials provided with the distribution.
             * Neither the name of the <organization> nor the
               names of its contributors may be used to endorse or promote products
               derived from this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
         ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
         WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
         DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
         (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
         LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
         ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
         (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
         SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries
Project-URL: Homepage, https://www.ogre3d.org
Project-URL: Source, https://github.com/OGRECave/ogre-audiovideo
Requires-Python: >=3.12
Requires-Dist: ogre-python<14.7,>=14.6.2
Description-Content-Type: text/markdown

# %Ogre Video and Audio Plugins {#mainpage}

This is the API reference for the Ogre Video and Audio plugins; contained within are the 
specifications for each class and the methods on those classes which you can 
refer to when using the library in your code. 

# Building

The audio plugin builds against the bundled [mojoAL](https://github.com/icculus/mojoAL)
OpenAL 1.1 implementation by default, which requires SDL2:

    cmake -B build .
    cmake --build build

Pass `-DOGGSOUND_USE_MOJOAL=OFF` to link against a system OpenAL implementation
instead. mojoAL does not support EFX or multichannel (4/5.1/6.1/7.1) buffer
formats.

Standalone Ogg Vorbis playback is decoded with the bundled
[stb_vorbis](https://github.com/nothings/stb). stb_vorbis has no streaming IO
callbacks, so streamed `.ogg` sounds keep the compressed file in memory. The
Theora video plugin still uses libogg/libvorbis for audio multiplexed into
video files.

## Licensing

The default audio build is entirely permissively licensed: OgreOggSound is
BSD-3-Clause, the bundled [mojoAL](https://github.com/icculus/mojoAL) OpenAL
implementation is zlib, stb_vorbis is public domain/MIT, and SDL2 is zlib.
This allows static linking into closed-source applications without LGPL
obligations.

Building with `-DOGGSOUND_USE_MOJOAL=OFF` links against OpenAL Soft instead,
which is LGPL-2.1-or-later and must be redistributed according to its license.

# OggSound 

The %OgreOggSound library is designed to provide a simple, quick and easy method
of adding audio to an OGRE based application. Its primarily a wrapper around the 
OpenAL audio library, but its design focus is seamless integration with OGRE 
based applications. 

It hides all the mundane setup and updating procedures needed by OpenAL, and 
condenses the functionality down to a clean and simple OGRE-fied interface.

## Features

* .ogg file format support
* uncompressed .wav file support
* In memory and streaming support
	* Load whole sound into memory
	* Stream sound from a file
* Optional multithreaded streaming
* Multichannel audio support
* Full 2D/3D audio support
	* spatialized sound support using mono sound files
	* 2D/multichannel support 
* Full control over 3D parameters
	* All 3D properties exposed for customisation
	* Global attenuation model configurable
	* Global sound speed configurable
	* Global doppler effect configurable
* Playback seeking 
* Cue points - Set 'jump-to' points within sounds
* Configurable loop points
	* By default a sound would loop from start to end, however a user can customise this by offsetting the start point of the loop per sound.
* Temporary sounds
	* Allows creation and automatic destruction of single-play/infrequent sounds.
* Source management
	* Sources are pooled 
	* Sources are automatically re-used when a sound requests to play
	* Sounds are re-activated if temporarily stopped.
* OGRE integration support
	* Sound objects are derived from MovableObject
	* can be attached directly into scene graph via SceneNodes
	* Automatically updates transformations
* Audio capturing support to WAV file.
* XRAM hardware buffer support 
	* Currently experimental
* EFX effect support
	* Support for attaching EFX filters/effects to sounds if hardware supported
	* Support for EAX room reverb presets
* Volume control
* Pitch control
* Loop control
* Fully Documented

# Theora Video Plugin

The Theora Video plugin allows referencing theora streams as @ref External-Texture-Sources.

## Features

* Integrates into Ogre3D as a FrameListener
* Supports loading videos from material files
* optional yuv->rgb conversion via shader
  
