2020-01-04 05:55:49 +01:00
|
|
|
# palace
|
2020-01-24 11:00:21 +01:00
|
|
|
Palace is a Python 3D audio API wrapping around [alure].
|
2019-12-25 16:41:38 +01:00
|
|
|
To quote alure's README,
|
2019-12-22 10:26:51 +01:00
|
|
|
|
2019-12-25 16:41:38 +01:00
|
|
|
> It uses OpenAL for audio rendering, and provides common higher-level features
|
|
|
|
> such as file loading and decoding, buffer caching, background streaming,
|
|
|
|
> and source management for virtually unlimited sound source handles.
|
|
|
|
|
|
|
|
## Features
|
2020-02-02 08:49:15 +01:00
|
|
|
In some sense, what palace aimes to be to [OpenAL Soft] is what [ModernGL]
|
2019-12-25 16:41:38 +01:00
|
|
|
is to OpenGL (except that all the heavy-lifting are taken are by alure):
|
|
|
|
|
2020-05-04 17:50:08 +02:00
|
|
|
* 3D positional sound rendering
|
|
|
|
* Environmental effects: reverb, atmospheric air absorption,
|
2019-12-25 16:41:38 +01:00
|
|
|
sound occlusion and obstruction
|
|
|
|
* Binaural (HRTF) rendering
|
|
|
|
* Out-of-the-box audio decoding of FLAC, MP3, Ogg Vorbis, Opus, WAV, AIFF, etc.
|
2020-05-04 17:50:08 +02:00
|
|
|
* Modern Pythonic API: `snake_case`, `@property`, `with` context manager,
|
2019-12-25 16:41:38 +01:00
|
|
|
type annotation
|
2019-12-22 10:26:51 +01:00
|
|
|
|
|
|
|
## Installation
|
2020-01-24 11:00:21 +01:00
|
|
|
### Prerequisites
|
2020-02-01 09:09:54 +01:00
|
|
|
Palace requires Python 3.6+ for runtime and [pip] for installation.
|
2019-12-25 16:41:38 +01:00
|
|
|
|
2020-01-24 11:00:21 +01:00
|
|
|
### Via PyPI
|
2020-02-01 09:09:54 +01:00
|
|
|
Palace can be install from the [Python Package Index][PyPI] via simply
|
|
|
|
|
|
|
|
pip install palace
|
|
|
|
|
2020-04-10 15:19:35 +02:00
|
|
|
Wheel distributions are built exclusively for amd64. Currently, only GNU/Linux
|
2020-05-02 16:07:02 +02:00
|
|
|
and macOS are properly supported. If you want to help packaging for Windows,
|
|
|
|
please see [GH-1] on our issues tracker on GitHub.
|
2020-04-01 10:17:23 +02:00
|
|
|
|
2019-12-25 16:41:38 +01:00
|
|
|
### From source
|
2020-01-24 11:00:21 +01:00
|
|
|
Aside from the build dependencies listed in `pyproject.toml`, one will
|
2020-03-15 09:12:42 +01:00
|
|
|
additionally need compatible Python headers, [alure], a C++14 compiler,
|
2020-02-01 09:09:54 +01:00
|
|
|
[CMake] 2.6+ (and probably `git` for fetching the source).
|
|
|
|
Palace can then be compiled and installed by running
|
2020-04-01 10:17:23 +02:00
|
|
|
|
|
|
|
pip install git+https://github.com/McSinyx/palace
|
2019-12-25 16:41:38 +01:00
|
|
|
|
|
|
|
## Usage
|
2020-01-04 05:55:49 +01:00
|
|
|
One may start with the `examples` for sample usage of palace.
|
2020-04-10 15:19:35 +02:00
|
|
|
For further information, Python's `help` is your friend and
|
|
|
|
the API is also available for [online reference][API].
|
2019-12-25 16:41:38 +01:00
|
|
|
|
2020-05-02 16:07:02 +02:00
|
|
|
## Contributing
|
|
|
|
Our documentation contains [a brief guide][contrib] which may help you
|
|
|
|
get started with the development. We also think that you might find
|
|
|
|
[our design principles][design] appealing as well.
|
|
|
|
|
2020-01-24 11:00:21 +01:00
|
|
|
## License and Credits
|
2020-04-10 15:19:35 +02:00
|
|
|
Palace is free software: you can redistribute it and/or modify it
|
|
|
|
under the terms of the [GNU Lesser General Public License][LGPLv3+]
|
|
|
|
as published by the Free Software Foundation, either version 3
|
|
|
|
of the License, or (at your option) any later version.
|
2020-01-24 11:00:21 +01:00
|
|
|
|
2020-05-02 16:07:02 +02:00
|
|
|
[The full list of works bundled with palace and other credits][copying]
|
|
|
|
can be found in our documentation.
|
2020-04-28 17:43:42 +02:00
|
|
|
|
2020-01-24 11:00:21 +01:00
|
|
|
[alure]: https://github.com/kcat/alure
|
2020-02-02 08:49:15 +01:00
|
|
|
[OpenAL Soft]: https://kcat.strangesoft.net/openal.html
|
2020-01-24 11:00:21 +01:00
|
|
|
[ModernGL]: https://github.com/moderngl/moderngl
|
|
|
|
[Cython]: https://cython.org/
|
2020-02-01 09:09:54 +01:00
|
|
|
[pip]: https://pip.pypa.io/en/latest/
|
2020-02-02 08:49:15 +01:00
|
|
|
[PyPI]: https://pypi.org/project/palace/
|
2020-01-24 11:00:21 +01:00
|
|
|
[GH-1]: https://github.com/McSinyx/palace/issues/1
|
2020-02-01 09:09:54 +01:00
|
|
|
[CMake]: https://cmake.org/
|
2020-08-24 16:57:53 +02:00
|
|
|
[API]: https://mcsinyx.github.io/palace/reference.html
|
|
|
|
[contrib]: https://mcsinyx.github.io/palace/contributing.html
|
|
|
|
[design]: https://mcsinyx.github.io/palace/design.html
|
2020-04-10 15:19:35 +02:00
|
|
|
[LGPLv3+]: https://www.gnu.org/licenses/lgpl-3.0.en.html
|
2020-08-24 16:57:53 +02:00
|
|
|
[copying]: https://mcsinyx.github.io/palace/copying.html
|