AUDIENCE
Spatial Audio Software
----------------------

AUDIENCE for Pd (Audience4Pd):
Full Package Distribution. Availability of some objects subject to acknowledging license agreements. AVAILABLE ONLY FOR DEVELOPERS AND LICENSEES. DO NOT DISTRIBUTE.

OpenAUDIENCE (OA):
Free Package Distribution, except for proprietary codes.

LICENSE INFORMATION: GPL, BSD and other licenses apply. See release notes on individual files.

----------------------
Copyright AUDIENCE team, 2005-2012
Contact info: audience@lsi.usp.br
----------------------

This file has information about:

* what is audience and how it works (few words)
* distribution organization (directory structure)
* how development works (how you work colaboratively here)
* instalation and operational notes
* versions reference guide
* documentation (helps, guides and faqs)
* list of all files in the distribution

----------------------
WHAT is AUDIENCE and HOW it works

Audience4Pd is a software library of objects and patches for Pure Data that permits the creation, manipulation and interactive reproduction (auralization) of spatial sound scenes using a 4-layer functional hierarchy.

The library works through patches of "functional blocks" forming a processing chain by connecting outlets to inlets. 

All the functional blocks are either part of the Audience4Pd library, of the Pd basic package distribution, or part of the additional libraries included in the Pd extended version. Some Audience4Pd blocks implement complex functions written in C/C++ (externals).

Most blocks have their usage explained in HELP files accessed by right-clicking on block. Additional information may appear on the Pd console window. Binaries (compiled externals) are available for Windows (includes dll's and executables), for MAC OS X (pd_darwin) and for Linux (pd_linux).

Audience4Pd is the reference to the full distribution, containing also proprietary codes. 

OpenAUDIENCE is the free distribution with compiled components and open abstractions downloadable from http://www.lsi.usp.br/audience/ and other sources.

Pd is "Pure Data" developed by Miller Puckette and others. Miller's original distribution and the Extended version (+ others' libs) are downloadable from http://puredata.info. 

---------------------
DIRECTORY Structure

AUDIENCE files are sorted out through a logical organization structure:
 
- app: applications and demos
- aux: auxiliary objects (see NOTE 1 below)
- bin: binaries (executable files) necessary in some applications
- doc: documentation (see NOTE 2 below)
- img: images used in gui blocks
- include: include files required for c/c++ compiling/building
- L1: layer 1 patches and externals (including L1 binaries)
- L2: layer 2 patches and externals (including L2 binaries)
- L3: layer 3 patches and externals (including L3 binaries)
- L4: layer 4 patches and externals (including L4 binaries)
- lib: external libs needed for compiling/building and usage
- obsolete: obsolete patches and externals
- snd: sounds
- src: source files
- tst: test patches

This structure above used to be the actual directory structure until version 2.0.2. These were the general directions then: 

- Developer's and specific projects' files must be within a specific named sub-directory within "app". 
- Includes, lib files and source codes should be stored in "include", "lib" and "src" sub-directories. 
- Binaries should be stored either in the "bin" or the specific layer sub-dirs (L1, L2, L3, L4 and aux). 
- Sounds and images of specific applications should be stored inside their own sub-dirs. 
- Functional test-files and test-patches can be stored inside the "tst" sub-dir. 
- Documentation should come within the sub-directory "doc".

NOTE 1: In Windows the "aux" directory must be renamed to "auxiliar". See manual for details. This limitation does not apply anymore to v.2.0.3.

NOTE 2: Documentation includes manual, specifications and panflets. It might also include tutorials, white papers and guides.

Starting from version 2.0.3 the distribution package has the following directory structure:

audience
  /app: application, tutorials and demos
  /doc: documentation
  /include: include files
  /src: source files
  /tst: test patches
  /audce: includes aux, bin, lib, img, snd, L1, L2, L3, L4 files

NOTE: OS X binaries in v.2.0.3 are compiled on OS v.10.5.8.


OA packages starting from version 1.0.3 will include:

OA_doc: 
  /doc: documentation

OA_executable_core:
  /audce (aux, bin, lib, img, snd, L1, L2, L3, L4)
  /tst: test patches

OA_apps:
  /app: free application, demos and tutorials

OA does not include: 
  /include
  /src
  /bin and lib that are proprietary/restrict


-----------------------
HOW development works

Policies adopted from v.2.0.3 and on:

- Developer's new components may target functional blocks implementation in one or more layers. 
- While not stable, all developer's new objets/abstractions (and also source files) should be stored in a different directory, which may be also included in the Pd path. 
- Finished stable deliverables (e.g. binaries, abstractions, source codes, etc.) shall be moved to the main distribution directories.
- Help files and documentation shall be available in the /doc directory.


Policies adopted until v.2.0.2:

- Developer's new components will target functional blocks implementation in one or more layers.
- Each developer must have his/her own application environment as a sub-directory within "/app" directory, with source files stored in a "/src" directory and compiled itens in a "/bin" directory. All environment files must lie into a different directory structure other than the AUDIENCE/OA one.
- Finished stable archives (e.g. binaries, libraries, plain functions patches, executables, source codes, etc) for the distribution will be moved to the appropriate directory in the main tree.
- Stable source codes shall be stored to the "src" directory, where all versions of source files must lie.


Policies adopted in previous development stages:

- Developers should have their own projects directory or development workspace (named such as "fulano_projects") away from the main tree. 
- Specific archives ineherent to his/her sw environment should exist only in this directory. 


-----------------------
INSTALLATION and Operational Notes

To use AUDIENCE v.2.0.3 / OA v.1.0.3 you have to:

- Install Pd (download from http://puredata.info)
- Create a shortcut to Pd executable in the Desktop (for a fast access)
- Open the Pd and look for the "Path" configuration
- Include in the Pd path the /audce directory from AUDIENCE package or from the OA executable core package. 


For AUDIENCE version 2.0.2 /OpenAUDIENCE version 1.0.2 and before the directory structure was different and must include the following:

- Include in the PD path the following AUDIENCE directories: "aux", "bin", "lib", "L1", "L2", "L3" and "L4" (the main layers directories)
- Additional directories shall be included if necessary (e.g. "app" sub-directories, "obsolete" for using obsolete/old patches and objects, and "tst" for calling test files)

Example:

C:/AUDIO/AUDIENCE_SW_Pack/audience/aux
C:/AUDIO/AUDIENCE_SW_Pack/audience/bin
C:/AUDIO/AUDIENCE_SW_Pack/audience/lib
C:/AUDIO/AUDIENCE_SW_Pack/audience/L1
C:/AUDIO/AUDIENCE_SW_Pack/audience/L2
C:/AUDIO/AUDIENCE_SW_Pack/audience/L3
C:/AUDIO/AUDIENCE_SW_Pack/audience/L4
C:/AUDIO/AUDIENCE_SW_Pack/audience/obsolete
C:/AUDIO/AUDIENCE_SW_Pack/audience/tst


For versions before AUDIENCE 2.0/OpenAUDIENCE 1.0 the directory structure was different and must include the following:

C:/AUDIO/AUDIENCE_SW_Pack/audience/bin
C:/AUDIO/AUDIENCE_SW_Pack/audience/patches/audience

- To work without GUI, use option -nogui
- To send messages via commandline, after loading the patch, -send "msg" 
- To turn on audio computation (AUDIO ON) use the message "pd dsp on 1"
- To change the working sampling frequency, modify it in the audio parameters of pd

In Windows the directory "aux" must be renamed to "auxiliar" and all references to things inside ".../aux" must be corrected as well.

Refer to the manual for complete installation and usage instructions (see /doc/manual directory).


-----------------------
VERSIONS Reference Guide (all distributions)

-------------
v.2.0.3 AUD / v.1.0.3 OA

Release date: 06/04/2012

- altered distribution package directory structure, concentrating executable core of objects and abstractions into /audce directory
- eliminated the aux, bin, lib, img, snd, L1, L2, L3 and L4 directories
- updated release notes and readme.txt's files
- updated test patches using obsolete items
- updated logo and sound addressing in test and help patches 

-------------
v.2.0.2 AUD / v.1.0.2 OA

Release date: 19/08/2011

- updated help files: audce_L4_amb_3rd~-help


Release date: 20/10/2010

- corrections in audce_L1_gui:
  added method for scale change and retrieve scale info with a bang
  corrected wrong objects positioning when scene is a rectangle
 
Release date: 10/09/2010

- updated test patches and cleaned tst directory
- updated header text in L1_scene_controller source
- updated audce_aux_move.pd
- updated obsolete directory

Release date: 03/09/2010

- update m_pd_h, m_imp.h, g_canvas.h with new Pd releases (aug/2010)
- corrections in audce_aux_mixer.c:
  "(t_newmethod) substituted for (t_method) in method audce_aux_mixer_tilde_setup
  re-encode audce_aux_mixer.c in UTF-8 text to solve MAC OS compilation errors
- corrections in audce_L1_gui.c:
  method ..._send_pos_rcv and ..._send_pos_src: removed "&" before "atoms" (to pass value, not reference)
  method audce_L1_gui_convert_pixel_to_meter and ..._convert_meter_to_pixel: renamed "meter" to "meterr" (last parameter in call and in all ocurrences in the function)
  removed NULL on method audce_L1_gui_pos_rcv
  "glist_getcanvas(glist)" substituted for "glist" in audce_L1_gui_delete method to solve Pd crash when terminating object
  elimination of NULL in return of void functions
  text review

-------------
v.2.0.1 AUD / v.1.0.1 OA
Release date: 13/08/2010

- updated makefile
- included new compiled externals and dlls for windows and mac
- updated documentation

-------------
v.2.0 AUD / v.1.0 OA
Release date: 01/07/2010

- updated README.txt files in each directory
- correcting and updating objects and patches, including release tag


Release date: 03/06/2010

- added L4 object for scene transport


Release date: 31/05/2010

- structure prepared for both distributions (AUD and OA)
- directory structured remodeled, including "snd" and "Li" sub-dirs
- objects and files reviewed and tagged including release notes
- included L2 CRR 2010 developments
- included aux mono and multichannel recording and playing objects
- overall review and updating objects, cleaned obsolete patches and objects
- included several new objects and patches, including tutorial/demo patches
- prepared comprehensive manual replacing previous "how-to's" docs

-------------
v.1.11
Date: 22/12/2009

- updated several README.txt within specific sub-direcotories
- inserted OA directory to document OpenAUDIENCE development
- updated directory tree for patches (including AMob, FreeSurround initial concepts, OGN set of patches and SAOC patches)

Date: 25/11/2008

- loaded AMob initials test patch
- loaded FreeSurround test patches
- loaded audce_L1_gui.dll new L1 GUI
- loaded audce_L1_gui source (21/11)

-------------
v.1.10
Date: 20/3/2008

- loaded L3 5.1 positioners (test patches)
- loaded auxiliar RM test patches (for SAOC): 6 > 5.1 patches
- loaded auxiliar volume patch corrections/improve
- loaded auxiliar blocks for clustering objects (5 objs for Ambisonics 3D)
- loaded L2 RM generator source (30/1/08) and aux_RM_posic source (30/1/08)
- loaded L2 RMgen.dll and help (20/3 and 30/1)

-------------
v.1.9
Date: 21/12/2007 

- loaded auxiliar RM_posic.dll (21/12/07)
- loaded L3 5.1 positioning patch (26/11/07)

Date: 23/11/2007

- loaded L3 MPS encoder demo
- loaded L4 MPS and aac decoder demo
- loaded saoc patches
- loaded L4 amb_3rd help update (4/9/07)

-------------
v.1.8
Date: 31/08/2007

- loaded L3 aacPlus encoder demo (14/08/07)
- uploaded auxiliar cluster/transcoding blocks:
  2 > 2.0

-------------
v.1.7
Date: 23/06/2007

- loaded MPEG Surround test patches 
- loaded MPS and aacPlus L3 encoders sources and binaries
- uploaded Rendering Matrixes generators for SAOC (test patches)
- uploaded aux_gui_srcfile, L3 3objects to Ambisoncs 1st and 2nd order
- uploaded auxiliar cluster/transcoding blocks:
  6 > 5.1, 
  4 > 4.0, 
  4 > 5.1, 
  n > multichannel
- loaded L4 MPS and aacPlus decoders dlls (for windows) (1/6/07)
- loaded aacPlus enc and dec binaries (.exe) (15/06/07) and ct-libisomedia.dll
- loaded spatial encoder and decoder binaries (.exe) (15/6/07)

-------------
v.1.6 
Date: 29/5/2007

- loaded L3 aacPlus decoder
- loaded L3 MPEG Surround decoder
- loaded L3 Ambisonics 3rd order encoders (L3_amb_*.dll)

-------------
v.1.5
Date: 14/11/2006


- version uploaded into CVS (incubadora.fapesp)

-------------
v.1.4
Date: 10/03/2006

-------------
V.1.3
Date: 23/05/2006

- new patch using object GRID for spatial position control
- started modifications on object GRID adequating for AUDIENCE proposals
- new object spatialcoder~ encodes in Ambisonics format, given the positions
- to be used without acousticsim

-----------------------
DOCUMENTATION

Documentation is available in the form of:

HELP files (per object/block/patch)
- some objects (blocks) and patches have their own help: use the right mouse click to access the help block
- check availability by "right-clicking" an object/block in your patch, then select "help"

Manual: includes
- AUDIENCE architecture
- AUDIENCE software w/ list of blocks and messages
- Installation and usage
- developers guide ("how-to")

Readme's inside the distribution directories

FAQ (frequently asked questions):
- version 1 available but obsolete; manual substitutes this version;
- version 2 pendent to release

Documentation history:

- "how-to" file was upgraded to AUDIENCE/OpenAUDIENCE manual/guide (2010)
- a work on OGN project provided new messages, ongoing work is updating the existing list of msgs (2008)
- "how-to write AUDIENCE blocks": version 4 available (updated style; revised up to date indicated in version's history)
- "how-to write AUDIENCE blocks": version 2 available (doc structure for "how to" approved; merges with version of "how-to write pd externals")


----------------------
CVS (software distribution repository) revision history: Obsolete. CVS not used anymore since v.2.0.1.


----------------------
LIST of all files in the distribution

Stable itens:

audce_aux_6.2.5.1.pd (converts 6 chns to 5.1)
audce_aux_convolver~.dll (windows)
audce_aux_convolver~.pd_darwin (mac os)
audce_aux_convolver~.pd_linux (linux)
audce_aux_convolver~-help.pd (help file)
  Note: convolvers use fftw3 library
audce_aux_dbvol~.pd (tiny patch for volume control in dB)
audce_aux_dynamicsend.pd (patch to send <msg> to <target_objects>)
audce_aux_file.pd (patch to associate a sound file to a sound object)
audce_aux_mixer~.dll (windows)
audce_aux_mixer~.pd_darwin (mac os)
audce_aux_mixer~.pd_linux (linux)
audce_aux_mixer~-help.pd (help file) (mixer requires no. channels)
audce_aux_move.pd (patch to move a sound source: motion automation)
audce_aux_mute~.pd (patch to mute a sound chain)
audce_aux_objtime.pd (patch to control time of a sound object in patch)
audce_aux_objtransp.pd (transport patch for a specific sound object)
audce_aux_objvol~.pd
audce_aux_objvol1~.pd (patch to control volume of sound objects in patch)
audce_aux_pf~.pd  (shortcut)
audce_aux_playmonofile~.pd (patch to play a mono sound file)
audce_aux_playmcfile~.pd (patch to play a multichannel sound file)
audce_aux_recordmc~.pd  (patch to record a multichannel sound file)
audce_aux_recordmc~-help.pd (help file)
audce_aux_samples2time.pd (patch to convert no. of samples in sound file to corresponding time)
audce_aux_time2samples.pd (patch to convert time to corresponding no. of samples in sound file)
audce_aux_time2samples-help.pd (help file)
audce_aux_vol~.pd
audce_aux_vol2ch~.pd 
audce_aux_volume~.pd (patch to control volume of a sound file/audio line)

fftw3.dll (v.1.1 2006)
 Note: fftw3.dll and fftw3 libraries are required to lie in the directories where the FFTW3 package installed them. See FFTW3 documentation for details. 

audce.gif (AUDIENCE mini logo)
base64.exe (program to compile GIF to Tcl/Tk displayable bitmap)
rcv_img.gif (reference receiver image)
rcv_img.txt (bitmap image ready to include inside externals)
speaker.gif
src_img.gif
src_img.txt (bitmap for externals)
wanderer.gif

cavaco.wav (Brazilian string instrument)
teste.wav (drums, 33', 48kHz/32bit)
teste48k16bit.wav (drums, 33', 48kHz/16bit)

audce_L1_gui.dll (win32 gui external)
audce_L1_gui.pd_darwin (mac os)
audce_L1_gui.pd_linux (linux)
audce_L1_gui-help.pd (gui help file)

audce_L2_allen.dll (win32)
audce_L2_allen.pd_darwin (mac os)
audce_L2_allen.pd_linux (linux)
audce_L2_allen-help.pd (help file)

audce_L3_3obj_amb1st~ (generate B-Format 1st order, 4 chns for 3 sources)
audce_L3_3obj_amb2nd~ (generate B-Format 2nd order, 9 chns for 3 sources)
audce_L3_3obj_amb3rd~ (generate B-Format 3rd order, 16 chns for 3 sources)
audce_L3_5obj_amb1st~ (generate B-Format 1st order, 4 chns for 5 sources)
audce_L3_5obj_amb3rd~ (generate B-Format 3rd order, 16 chns for 5 sources)
audce_L3_5.1render.pd (generate 5.1 signal set for positioned sound source)
audce_L3_5.1render-help.pd (help file)
audce_L3_amb_3rd~.dll (win32) 
audce_L3_amb_3rd~.pd_darwin (mac OS)
audce_L3_amb_3rd~.pd_linux (linux)
audce_L3_amb_3rd~-help.pd (help file)
 Note: ambisonics encoder up to 3rd order, uses R. Furse's coefs
audce_L3_ambirconv~ (convolves a IR generated by audce_L2_allen with a monophonic signal)

audce_L4_amb_3rd~.dll (win32)
audce_L4_amb_3rd~.pd_darwin (mac os)
audce_L4_amb_3rd~.pd_linux (linux)
audce_L4_amb_3rd~-help.pd (help file)
 Note: ambisonics decoder up to 3rd order, uses R. Furse's coefs
audce_L4_amb_rot~.pd_darwin (mac os)
audce_L4_amb_rot~.pd_linux (linux)
audce_L4_amb_rot~.dll (win32)
 Note: object for rotating ambisonics scene (B-Format field) around reference axes (see /src directory for more info on this external)
audce_L4_objplay~.pd (player for sound object)
audce_L4_objplay~-help.pd (help file)
audce_L4_objplay1~.pd (player for sound object)
audce_L4_objplay1~-help.pd (help file)
audce_L4_objplay2~.pd (player for sound object)
audce_L4_objplay2~-help.pd (help file)
audce_L4_sceneplay.pd (transport for a sound scene, holding several sound objects)


Itens under development (not stable):

audce_aux_recordmc2~
audce_aux_recordmcd~
audce_aux_recordmc2d~

audce_L3_2obj_amb1st~.pd
audce_L3_5obj_amb1st_2~.pd
audce_L3_5obj_amb1stv2~.pd
audce_L3_8obj_amb1st~.pd

audce_L1_scene_controller.dll
audce_L1_scene_controller.pd_darwin
audce_L1_scene_controller.pd_linux
 Note: lacks functionalities specification and help implementation


--
Itens available only in AUDIENCE full version (require NDA):

Stable:

aacPlusEnc.exe
aacPlusDec.exe
ct-libisomedia.dll (Coding Technologies AAC, proprietary codec)
aacPlusEnc (MAC OS binaries from aacPlus evalPack v.8.0.3)
aacPlusDec (MAC OS binaries from aacPlus evalPack v.8.0.3)
audce_L3_aacenc.dll (win32)
audce_L3_aacenc.pd_darwin (mac os)
audce_L3_aacenc.pd_linux (linux)
audce_L4_aacdec.dll (win32)
audce_L4_aacdec.pd_darwin (mac os)
audce_L4_aacdec.pd_linux (linux)
 Note: Coding Technologies aacPlus proprietary codec. Binaries for Linux were renamed with a "_linux" tail to accomodate them in this directory, since they originally were named exactly as the MAC OS binaries. To use them under linux it may be necessary to correct naming.


Under development (not stable):

audce_aux_convolver2~.pd_darwin (mac os)

audce_L2_RMgenerator.pd_darwin
audce_L2_RMgenerator.pd_linux
audce_L2_RMgen.pd_darwin
audce_L2_RMgen.pd_linux
audce_L2_RMgenerator.dll
audce_L2_RMgen.dll
audce_L2_RMgen-help.pd
audce_L2_crr-help.pd

 Note: RM (Rendering Matrix) objects part of MPEG SAOC/MPS experimental tests (2007/2008)

audce_L3_MPSenc.pd_darwin (mac os)
audce_L3_MPSenc.pd_linux (linux)
audce_L3_MPSenc.dll (win32)
audce_L3_crr2amb1~ (CRR to Ambisonics 1st. order encoding, convolves B-format IR with audio)

audce_L4_MPSdec.pd_darwin (mac os)
audce_L4_MPSdec.pd_linux (linux)
audce_L4_MPSdec.dll (win32)
spatialenc.exe (Audience MPS 2007 tests)
spatialdec.exe (Audience MPS 2007 tests)

 Note: MPS (MPEG Surround) encoder and decoder from MPEG reference sw, experimental development (2007/2008)


--
Files not included in this version:

audce_aux_2.2.2.0.pd (converts 2 chns to 2.0 - to be updated)
audce_aux_4.2.4.0.pd (converts 4 chns to 4.0 - to be updated)
audce_aux_4.2.5.1.pd (converts 4 chns to 5.1 - to be updated)
audce_aux_n.2.mc.pd (converts n chns to mc file - to be updated)
audce_aux_nwaves2mc.pd (obsoleted)
audce_aux_writemc.pd (obsoleted) 
audce_aux_counter.pd
partconv~.pd_darwin (mac os)
audce_aux_srcfile.pd (play audio files, obsoleted)
test_audce_aux_srcfile.pd (obsoleted)
audce_L3_amb_mix~.pd (obsoleted)


--
Obsolete files included in this version: 

audce_gui_grid.dll (win32)
audce_gui_grid.pd_darwin (mac os)

----------------------
DISCLAIMER

This software library runs on top of the third party software Pure Data Extended version. By using this the user complies with all license terms included in the Pure Data Extended version and in the individual objects and abstractions documentation. There is no warranty granted in its usage and the developers in no event shall be liable for any damages arising out of the use or inability to use this software library. All rights are reserved.

AUDIENCE4Pd & OpenAUDIENCE (C) Mar2012

