Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

better documentation #28

Closed
5 tasks
ahicks92 opened this issue Nov 12, 2020 · 15 comments
Closed
5 tasks

better documentation #28

ahicks92 opened this issue Nov 12, 2020 · 15 comments
Milestone
1.0.0

Comments

@ahicks92
Copy link
Collaborator

We need:

  • More tutorials
  • A proper README
  • Reorganize the manual to split up the object reference by category, and maybe fold some of the concepts in closer to the objects they're for.

And things with significantly less value that need to be decided on:

  • do we want a blog? I'm leaning toward no, but it isn't necessarily a bad idea.
  • How much effort should be put into writing and maintaining a section of the manual for potential contributors? This worked well for the Rust compiler and there's enough subtlety that it might be useful for us, but it's unclear if that's enough to make up for needing to keep it up to date.
@ahicks92 ahicks92 added this to the 1.0.0 milestone Nov 12, 2020
ahicks92 added a commit that referenced this issue Dec 27, 2020
@ahicks92
Add syz_pause and syz_play to all the relevant places in the manual
174aa9c 
This documentation will be improved further when we do #28

Closes #23
@chrisnorman7
Copy link
Contributor

So I'd like to help, and this area seems like one I could do some good things in.

Do you have anywhere particular you'd like me to start? I'm thinking Tutorials, although they'd have to be in Python.

Is there is a particular folder you'd like stuff in, a particular style, that sort of thing?

@Tetsujinfr
Copy link

hi
I struggle to get started with HRTF. I had a quick look through the doc but I struggle to find my way.
I started with the python 3d media player, but after reading this I realised that stereo panning has been turned on by default recently, and I do not know how to enable HRTF back. The panning is quite brutal with the stereo mode, by default it is like balanced stereo if x=0, full left if x<0 and full right if x>0, with no smooth transition at all. Not sure if I am doing something wrong, but I am not sure what this example is meant to achieve without HRTF enabled by default anymore.

Then I tried to locate references to HRTF in the doc, there were not that many matches to my surpise. The closet page I found what the 3D panning article, but I do not know how to use the HRTF panning mode still. I search for instance SYZ_PANNER_STRATEGY_HRTF in the git repo code base but could not find a match.

I had a quick look at the python examples in the example folder (fdn_reverb, echo and noise) but no evidence of HRTF settings in those neither.

Please help me, I am lost on how to enable and use HRTF with the lib. thanks a lot.

@Tetsujinfr
Copy link

Happy to help on writing a quick python tutorial complement, but I need your help to get started. I am not sure to understand if the SYZ_P_PANNER_STRATEGY is defined at the context level or the source level.

Let's say I start with the 3D media player python example below, how can setup the HRTF mode?

import sys
import synthizer
if len(sys.argv) != 2:
    print(f"Usage: {sys.argv[0]} <file>")
    sys.exit(1)

synthizer.configure_logging_backend(synthizer.LoggingBackend.STDERR)
synthizer.set_log_level(synthizer.LogLevel.DEBUG)
with synthizer.initialized():
    ctx = synthizer.Context( ???)
    ???

thanks a lot.

@ahicks92
Copy link
Collaborator Author

@chrisnorman7
I missed your comment. The answer is it's probably premature. Let me finish breaking the library's API first.

@Tetsujinfr
As I put in the other issue:

context.panner_strategy = synthizer.PannerStrategy.HRTF

And then create your sources.

@Tetsujinfr
Copy link

Thanks, all good now with enabling HRTF.
I got a few question regarding the HRTF rendering but I will open a new issue or leverage another one if it already exists.

ahicks92 added a commit that referenced this issue Apr 3, 2021
@ahicks92
Increment/decrement event handle reference counts to guarantee validi…
1388c7a 
…ty of handles for the duration of event processing.

And add a flag so that users may conveniently request that they take ownership
of the handles instead of them being freed at `syz_eventDeinit` time.

This solves the lifetime issue in #21 and makes events safe to use in
multithreaded contexts.  For bindings such as Rust, it is now possible to
put handles behind smart pointer abstractions and support cloning by taking on
the burden of translating event handles out, without having to e.g. figure out
typesafe ways to keep the user from "stealing" event handles (for bindings like
Python where preserving object tidentity is important, only the "this handle
definitely lives long enough" concern applies).

Doc updates will be handled as part of #28 in one go in what is essentially
going to be a rewrite of most of the manual.
@davidkreynolds
Copy link

Hi,
I'm currently attempting to write games for the visually impaired. Standardly, when writing a space shoot up, pitch dictates the Y cordinate, and pan the X coordinate. Can I have some clarification on the following:

  1. I want to play a repeated sound (Very short), but depending on the location of the object making the sound, I need to adjust pitch and pan accordingly. The pitch and pan should relate to the relative position of the enemy and the player.
  2. I did look at the manual, but could find nothing that my meager brain could interpret as a solution to this.
    Many thanks,
    David.

@ahicks92
Copy link
Collaborator Author

You need BufferGenerator with the pitch_bend property and PannedSource with the panning_scalar property. Those two together should do what you want.

Avoid StreamingGenerator for this use case until #29 is closed.

ahicks92 added a commit that referenced this issue Jun 13, 2021
@ahicks92
Bind loading Libsndfile to Python
be3b4f0 
This starts our strategy for better docs as well: we will be porting the set of C
testbed examples to every opfficial binding.

Refs #28 for docs. We don't seem to have an open libsndfile issue.
@davidkreynolds
Copy link

davidkreynolds commented Jun 13, 2021 via email

@davidkreynolds
Copy link

Hi Austin,
Can you point me in the direction of some usage/coding examples?
Thanks.

@ahicks92
Copy link
Collaborator Author

Clone the 0.9-dev branch and check examples or bindings/python/examples and you can see what this looks like once 0.9 lands. That's all I've got. @chrisnorman7 has at least one open source game written with it.

Can you articulate what's hard about this library? The big example in the manual should be enough to figure most things out if combined with the object references. There's not supposed to be anything complicated enough here to need a lot of detailed demonstration, at least not until custom streaming stuff in 0.9 that's not out yet.

If your issue is a lack of Python-specific documentation, this isn't going to be fixed: I don't have the bandwidth to maintain two sets of everything. Shortly once I take over the Rust bindings that will be 3. It doesn't scale for a weekend project. But the C API translates in a very straightforward manner and you should be able to figure it out by reading the cython or even just playing with it in a shell.

@davidkreynolds
Copy link

davidkreynolds commented Jun 18, 2021 via email

@ahicks92
Copy link
Collaborator Author

Yeah, of course you can have more than one sound. You just make more sources, or hook more generators to one source, depending. For what it's worth I am blind, and I am writing this to try to make an MMO for the blind, so I already know what you're trying to do.

pitch_bend is a multiplicative factor. That is to say that if you make a buffer of a tone at 300 hz and you put it on a generator with pitch_bend=2.0, you get a tone at 600 hz. If you're looking for an audio library that can take a sound and frequency shift it to a given frequency directly, you're not going to find one that can do so in realtime. You have to work out the ratio yourself and have whoever is doing sound design make sounds with the same primary frequency so that you know what this should be.

For what it's worth, this issue isn't about answering random questions. It's about collecting documentation requirements and tracking documentation improvements. Can I assume that you're either (1) new to audio libraries or (2) new to programming, or is Synthizer really that much more confusing than other options? I am trying to determine how to turn our discussion into something actionable.

@davidkreynolds
Copy link

davidkreynolds commented Jun 19, 2021 via email

@ahicks92
Copy link
Collaborator Author

I don't mind being bothered, and I probably need to set up a proper support mechanism. I'm just trying to direct stuff that's not related to the issue tracker out of the issue tracker. For now, if you need further help my e-mail is ahicks@ahicks.io. And of course feel free to open issues if you find bugs.

I'll look at getting a google groups or something going in the next few days. I really should have done it a long time ago.

ahicks92 added a commit that referenced this issue Jun 20, 2021
@ahicks92
Rewrite half the manual.
29c3c30 
None of these commits are going to be super informative.

Refs #28
@ahicks92
Copy link
Collaborator Author

ahicks92 commented Jul 3, 2021

Closing this out because I just rewrote the manual, massively expanding it in the process. Taking it further than I now have is infeasible.

@ahicks92 ahicks92 closed this as completed Jul 3, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
1.0.0
Development

No branches or pull requests
4 participants
@chrisnorman7 @ahicks92 @davidkreynolds @Tetsujinfr