Metadata-Version: 2.1
Name: PyOpenAL
Version: 0.7.3a1
Summary: OpenAL integration for Python
Home-page: https://github.com/Zuzu-Typ/PyOpenAL
Author: Zuzu_Typ
Author-email: zuzu.typ@gmail.com
License: Unilicense
Description: # PyOpenAL
        
        PyOpenAL provides OpenAL bindings for python as well as an interface to them.
        
        It also provides a simple way to play WAVE and - if [PyOgg](https://github.com/Zuzu-Typ/PyOgg) is installed - even OGG Vorbis, OGG Opus and FLAC files.
        
        You can install it using the PyPI:
        
        	pip install PyOpenAL
        
        	
        PyOpenAL requires a shared OpenAL library (e.g. OpenAL32.dll), one of which the Windows distributions already come with ([OpenAL Soft](http://kcat.strangesoft.net/openal.html) by kcat). 
        You can use the [official OpenAL library](http://www.openal.org/) (deprecated) or any other compatible library, like the aforementioned [OpenAL Soft library](http://kcat.strangesoft.net/openal.html), which is still actively developed.
        
        PyOpenAL provides OpenAL bindings, as you would find them in C++, meaning you can follow any [OpenAL C++ tutorial](http://www.openal.org/documentation/) with Python.
        OpenAL's methods expect C types as arguments, which means you will have to convert Python's types to C types using [ctypes](https://docs.python.org/3/library/ctypes.html) if you want to use them directly.
        Don't worry though, PyOpenAL can be used without the need to do that.
        
        I removed the support for ALUT, because it is basically impossible to build nowadays. If you want ALUT support, please use the original [python-openal from forrestv](https://github.com/forrestv/python-openal)
        
        ### Examples
        ##### Playing a wave file
        ```python
        # import PyOpenAL (will require an OpenAL shared library)
        from openal import * 
        
        # import the time module, for sleeping during playback
        import time
        
        # open our wave file
        source = oalOpen("test.wav")
        
        # and start playback
        source.play()
        
        # check if the file is still playing
        while source.get_state() == AL_PLAYING:
        	# wait until the file is done playing
        	time.sleep(1)
        	
        # release resources (don't forget this)
        oalQuit()
        ```
        ##### Playing an OGG Opus file (with PyOgg)
        ```python
        	# This requires PyOgg to be installed ( pip install pyogg )
        	from openal import * 
        	
        	import time
        	
        	source = oalOpen("test.opus")
        
        	source.play()
        
        	while source.get_state() == AL_PLAYING:
        		time.sleep(1)
        		
        	# remember, don't forget to quit
        	oalQuit()
        ```
        ##### Streaming a file
        ```python
        	from openal import *
        
        	# The following two lines are optional. You can use them, if you can't update the stream frequently enough
        	# This one specifies how much data is supposed to be stored in each buffer (only applies for OGG Vorbis and Opus files)
        	pyoggSetStreamBufferSize(4096*4)
        	# This one sets the maximum amount of buffers to be created at a time
        	oalSetStreamBufferCount(4)
        
        	sourceStream = oalStream("test.ogg")
        
        	sourceStream.play()
        
        	while sourceStream.get_state() == AL_PLAYING:
        		# do stuff
        		[...]
        		
        		# update the stream (load new data)
        		# if you don't do this repeatedly, the stream will suffocate
        		sourceStream.update()
        		
        	oalQuit()
        ```
        ### Using OpenAL functions
        ```python
        	# Here we only import OpenAL's functions 
        	# (in case you don't need or want PyOpenAL's functions and classes)
        	from openal.al import *
        	from openal.alc import *
        
        	[...]
        	
        	# It's as simple as that:
        	alDistanceModel(AL_INVERSE_DISTANCE_CLAMPED)
        	
        	# Or a little more complicated, it really depends:
        	alSourceUnqueueBuffers(source_id, 1, ctypes.pointer(ctypes.c_uint(buffer_ids[id])))
        	
        	[...]
        ```
        ### Reference (for PyOpenAL's own classes and functions)
        ```
        	<method> oalInit(device_specifier = None, context_attr_list = None) -> None
        		# initializes PyOpenAL
        		# this is called automatically, unless you set OAL_DONT_AUTO_INIT
        			<c_char_p> device_specifier # you can set a custom device with this
        			<c_int_p> context_attr_list # you can pass additional arguments to context creation
        		
        	<method> oalGetInit() -> <bool> initialized
        		# finds out wether or not PyOpenAL is initialized
        			
        	<method> oalQuit() -> None
        		# exits out of OpenAL and destroys all existing Sources and Buffers
        		
        	<method> oalOpen(path, ext_hint = None) -> Source
        		# loads a WAVE / Ogg Vorbis / Ogg Opus / FLAC file to a Source object
        			<str> path # path to the file (relative or absolute)
        			<str> ext_hint # if the filetype is not wav, wave, ogg, vorbis or opus, you should supply a hint to the extension
        			
        	<method> oalStream(path, ext_hint = None) -> SourceStream
        		# loads a WAVE /  Ogg Vorbis / Ogg Opus / FLAC file to a SourceStream object, that streams the data
        		# you should use this instead of Source for Soundtracks or other long tracks (as it uses less memory)
        		# you will have to update it frequently to avoid suffocation of the stream
        		# you can neither rewind nor loop a SourceStream (currently)
        			<str> path # path to the file (relative or absolute)
        			<str> ext_hint # if the filetype is not ogg, vorbis or opus, you should supply a hint to the extension
        
        	<class> openal.Listener()
        		# class for hadling the listener (you)
        		# an instance of this class is created when you import PyOpenAL.
        		# it can be retrieved using oalGetListener()
        		# you do NOT have to create an instance yourself
        		
        		<method> Listener.move(v)
        			# move the listener by v
        				<tuple or list> v # a translation vector represented as (x, y, z)
        		
        		<method> Listener.move_to(v)
        			# set the listener's position to v
        				<tuple or list> v # a position vector represented as (x, y, z)
        				
        		<method> Listener.set_position(v)
        			# see Listener.move_to
        			
        		<method> Listener.set_orientation(v)
        			# sets the listener's orientation to v
        				<tuple or list> v # orientation represented as (frontX, frontY, frontZ, upX, upY, upZ)
        				
        		<method> Listener.set_velocity(v)
        			# sets the listener's velocity to v
        				<tuple or list> v # velocity represented as (vX, vY, vZ)
        				
        		<method> Listener.set_gain(value)
        			# sets the listener's gain (volume) to value
        				<float> value
        				
        	<method> openal.oalGetListener() -> Listener
        		# returns PyOpenAL's Listener
        		
        	<class> openal.Source(buffer_ = None)
        		# class for managing a source
        			<Buffer> buffer_ # where this source finds it's data
        			
        		<method> Source.play() -> None
        			# starts playing
        			
        		<method> Source.stop() -> None
        			# stops playback
        			
        		<method> Source.pause() -> None
        			# pauses playback (use play to resume)
        			
        		<method> Source.rewind() -> None
        			# goes back to the start of the track
        			
        		<float> Source.pitch
        			# the source's current pitch
        			
        		<float> Source.gain
        			# the source's current gain
        			
        		<float> Source.max_distance
        			# the source's current max_distance
        			
        		<float> Source.rolloff_factor
        			# the source's current rolloff_factor
        			
        		<float> Source.reference_distance
        			# the source's current reference_distance
        			
        		<float> Source.min_gain
        			# the source's current min_gain
        			
        		<float> Source.max_gain
        			# the source's current max_gain
        			
        		<float> Source.cone_outer_angle
        			# the source's current cone_outer_angle
        			
        		<float> Source.cone_inner_angle
        			# the source's current cone_inner_angle
        			
        		<float> Source.cone_outer_gain
        			# the source's current cone_outer_gain
        			
        		<vec3> Source.position
        			# the source's current position (use .x, .y, and .z to access it's items or .toTuple())
        			
        		<vec3> Source.velocity
        			# the source's current velocity (use .x, .y, and .z to access it's items or .toTuple())
        			
        		<vec3> Source.direction
        			# the source's current velocity (use .x, .y, and .z to access it's items or .toTuple())
        			
        		<bool> Source.relative
        			# wether or not the source is relative to the listener
        			
        		<int> Source.source_type
        			# the source's current source_type (either AL_UNDETERMINED, AL_STATIC or AL_STREAMING)
        			
        		<method> Source.set_pitch(value) -> None
        			# set the pitch for this source
        				<float> value # pitch
        				
        		<method> Source.set_gain(value) -> None
        			# set the gain for this source
        				<float> value # gain
        				
        		<method> Source.set_max_distance(value) -> None
        			# set the max_distance for this source
        				<float> value # max_distance
        				
        		<method> Source.set_rolloff_factor(value) -> None
        			# set the rolloff_factor for this source
        				<float> value # rolloff_factor
        				
        		<method> Source.set_reference_distance(value) -> None
        			# set the reference_distance for this source
        				<float> value # reference_distance
        				
        		<method> Source.set_min_gain(value) -> None
        			# set the min_gain for this source
        				<float> value # min_gain
        				
        		<method> Source.set_max_gain(value) -> None
        			# set the max_gain for this source
        				<float> value # max_gain
        				
        		<method> Source.set_cone_outer_gain(value) -> None
        			# set the cone_outer_gain for this source
        				<float> value # cone_outer_gain
        				
        		<method> Source.set_cone_inner_angle(value) -> None
        			# set the cone_inner_angle for this source
        				<float> value # cone_inner_angle
        				
        		<method> Source.set_cone_outer_angle(value) -> None
        			# set the cone_outer_angle for this source
        				<float> value # cone_outer_angle
        				
        		<method> Source.set_position(value) -> None
        			# set the position for this source
        				<tuple or list> value # position
        				
        		<method> Source.set_velocity(value) -> None
        			# set the velocity for this source
        				<tuple or list> value # velocity
        				
        		<method> Source.set_looping(value) -> None
        			# set the looping for this source
        				<bool> value # looping
        				
        		<method> Source.set_direction(value) -> None
        			# set the direction for this source
        				<tuple or list> value # direction
        				
        		<method> Source.set_source_relative(value) -> None
        			# set the source_relative for this source
        				<bool> value # source_relative
        				
        		<method> Source.set_source_type(value) -> None
        			# set the source_type for this source
        				<int> value # source_type
        				
        		<method> Source.set_buffer(buffer_) -> None
        			# set the buffer for this source
        				<Buffer> value # buffer
        				
        		<method> Source.get_state() -> <int> state of the Source (e.g. AL_PLAYING, AL_STOPPED,etc.)
        			# get the current state of the source
        			
        	<class> openal.SourceStream(stream)
        		# class for managing a source in streaming mode
        			<PYOGG-Stream> stream # where the buffer gets it's data from
        			
        		<method> update() -> <bool> playing
        			# load more data to play (if necessary). 
        			# if you don't call this frequently, the source will stop playing after it reaches the last buffer
        			# in that case you should consider increasing the buffer size or amount using oalSetStreamBufferCount or pyoggSetStreamBufferSize
        		
        	<class> openal.Buffer(*args)
        		# class for managing OpenAL buffers
        			<File or tuple or list> args # what to fill the buffer with (either y PyOgg file or a tuple / list with [format, data, length, frequency])
        		
        		<method> Buffer.fill(*args) -> None
        			# fill the buffer
        				<File or tuple or list> args # what to fill the buffer with (either y PyOgg file or a tuple / list with [format, data, length, frequency])
        			
        		<method> Buffer.destroy() -> None
        			# destroy this buffer
        			
        	<class> openal.StreamBuffer(stream, count)
        		# class for managing OpenAL buffers for audio streaming
        			<PYOGG-Stream> stream # from where to get the data
        			<int> count # how many buffers to create (usually OAL_STREAM_BUFFER_COUNT, which is 2 initially)
        		
        		<method> Buffer.fill_buffer(id_) -> None
        			# fill the buffer
        				<int> id_ # load some data into this buffer
        			
        		<method> Buffer.destroy() -> None
        			# destroy this streambuffer
        			
        	<method> oalGetEnum(enum) -> <str> ENUM
        		# returns a literal representation of enum 
        			<int> enum # AL_ or ALC_ enumerator
        			
        	<method> oalGetALEnum(enum) -> <str> ENUM
        		# returns a literal representation of an AL_ enum 
        			<int> enum # AL_ enumerator
        			
        	<method> oalGetALCEnum(enum) -> <str> ENUM
        		# returns a literal representation of an ALC_ enum 
        			<int> enum # ALC_ enumerator
        			
        	<method> oalGetContext() -> <int> context
        		# returns the context used by PyOpenAL
        		
        	<method> oalGetDevice() -> <int> device
        		# returns the device used by PyOpenAL
        		
        	<method> oalSetAutoInit(val) -> None
        		# changes wether or not PyOpenAL initializes automatically
        			<bool> val # wether or not to auto-init
        			
        		# The other methods and variables are the same as in Source 
        		# (note that you can't loop, because the file can be read only once (by now))
        ```
Keywords: OpenAL 3D game Xiph ogg vorbis opus sound playback audio
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Games/Entertainment
Classifier: License :: Public Domain
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Description-Content-Type: text/markdown
