Skip to content

Commit cceb57f

Browse files
wsc1wsc1
authored
Merge pull request #8 from wsc1/master
reorganised for many ports
2 parents b8dd06b + ed8f777 commit cceb57f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+1354
-658
lines changed

‎Contributing.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Contributing to zikichombo.org/sio
2+
3+
1. If you are filing an issue for a bug report, please specify the system,
4+
version, environment and to the extent possible a small reproducer.
5+
6+
1. For porting, see [the porting guide](Porting.md). [ZikiChombo](http://zikichombo.org)
7+
supports 3rd party independently licensed ports as well ports distributed
8+
with this sio module. To contribute to the zikichombo.org/sio distribution,
9+
we need an out-of-github band confirmation, for example by [email](contrib@zikichombo.org),
10+
to participate as an author in our shared author BSD License.
11+
12+
1. General discussion relating to ports, entry points, sio project design are
13+
welcome on the issue tracker, please label any new issues with "discussion: "
14+
to help distinguish these from bugs.
15+
16+
17+

‎Porting.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Porting Guide
2+
3+
## Status of Ports
4+
The status of ports is kept in the main module [README](README.md).
5+
6+
## Overview
7+
ZikiChombo sio code has a porting process that is unconventional due to the
8+
nature of sound support on host systems. Usually, to port a system, one takes some
9+
desired cross-host functionality, such as a filesystem, and implements it with
10+
the OS or OS/hardware combination of interest and that's that (to make a long
11+
story short).
12+
13+
For sound, the problem is that hosts usually have multiple different software
14+
components as entry points to playing and capturing sound, and moreover these
15+
entry points have some mutually exclusive properties, such as lower bounds on
16+
latency, availability of duplex synchronised by hardware audio clock, ability
17+
to be shared accross many users or applications, etc.
18+
19+
Although the main CPU hardware architectures can certainly be a concern, it has
20+
not been so far in our experience. So we focus on organizing around host,
21+
which is taken to be the value of runtime.GOOS in a Go program.
22+
23+
# Hosts
24+
A host often has a hardware abstraction layer, hardware drivers, and some
25+
levels of interacting with these layers to coordinate and make secure demands
26+
related to playing and capturing sound on a device.
27+
28+
To simplify the end use case, we want to make all this transparent to the
29+
consumer of sio, and let them simply work with sound.{Source,Sink,Duplex}.
30+
31+
For each Host, ZikiChombo defines a default entry point to accomplish this.
32+
33+
All entry points are available both to the consumer of ZikiChombo and either
34+
with ZikiChombo or as 3rd party implementations. So if you're working with
35+
VoIP and have precise duplex echo cancellation needs, or a music app that
36+
listens and plays in real time with feedback, or writing a PulseAudio
37+
replacement, you're more likely to be interested in using a specialized entry
38+
point than the default.
39+
40+
There is a directory ZikiChombo/sio/ports/{runtime.GOOS} for each host.
41+
42+
# Entry Points
43+
An entry point defines a subset of the functionality listed in the main
44+
[README](README.md). ZikiChombo defines for each host (runtime.GOOS) a list of
45+
entry points which refer to the software layer with which the go program will
46+
communicate. These are named after the respective entry points in the main
47+
[README](README.md).
48+
49+
Each entry point defines a base set of functionality related to what the entry
50+
point supports: device scanning, device change notifications, playback,
51+
capture, duplex. Note the README excludes some functionality from some
52+
entry points and entry points may be incomplete.
53+
54+
The functionality is slightly more rich than implementing
55+
sio.{Capture,Play,Player,Duplex} to allow callers to achieve latency or other
56+
requirements. Package sio automatically uses the Entry point to apply defaults
57+
so that the caller may simply call sio.{Play,Player,Capture,Duplex}. Package
58+
sio also enforces that only one entry point may be in use at a time in one Go
59+
program.
60+
61+
Entry points can then be registered by a package implementing them in
62+
their init() function. Consumers of ZikiChombo may optionaly control which
63+
package implements a given entry point. The default is chosen by
64+
package initialisation order.
65+
66+
See [host](http://godoc.org/zikichombo.org/sio/host) for details.
67+
68+
The list of entry names for each host is defined in host/entry_{host}.go
69+
under the function host.Names().
70+
71+
72+
# Supporting concepts Devices, Inputs, Outputs, Duplex, Packets
73+
To implement an Entry Point, ZikiChombo provides some support code in
74+
[libsio](http://godoc.org/zikichombo.org/sio/libsio). The only required part
75+
of this code to reference is libsio/Dev to implement an Entry.
76+
77+
Other parts of this code, libsio.{Input,Output,Duplex,Packet,DuplexPacket}
78+
provide interfaces for synchronising with the host via Go channels and
79+
implementations to adapt these structures to sound.{Source,Sink,Duplex}.
80+
81+
## Import directions
82+
Package zikichombo.org/sio imports the package implementing entry points
83+
for registration side effects
84+
85+
```
86+
import _ "zikichombo.org/sio/ports/{runtime.GOOS}"
87+
```
88+
89+
Packages implementing the entries should import "zikichombo.org/sio/host" and
90+
call
91+
```
92+
host.RegisterEntry(mySuperReliableEntry)
93+
```
94+
95+
These packages may also import zikichombo.org/libsio.
96+
97+
98+
99+
# Duplex
100+
101+
Duplex support is intended for synchronized input/output. Systems which simply
102+
buffer underlying independent I+O and loosely synchronize with the slack that
103+
results from the buffering should consider not implementing Duplex and just
104+
letting the caller use sound.{Source,Sink} synchronously. Ideally, duplex
105+
should be audio hardware clock synchronized as in Apple's Aggregate devices.
106+
Duplexing I+O ringbuffers which are independently clocked to the same sample
107+
rate are acceptable but less reliable especially for long sessions. PortAudio
108+
actually supports duplex connections which have different sample rates. We
109+
recommend that this not be done to preserve the reliability of latency in
110+
Duplex implementations.
111+
112+
# Build tags
113+
114+
Submitted ports and tests which produce or capture sound should use the build
115+
tag "listen" so that they do not run by default but are easily invokable with
116+
117+
```
118+
go test zikichombo.org/sio/... -tags listen
119+
```
120+
121+
122+
# 3rd Party Ports
123+
To have an independently distributed port listed here, please file an issue.
124+
We only list the most recent zc version/port version pairs here.
125+
126+
| Port | zc version | Port version |
127+
-------|------------|--------------|
128+
| - | v0.0.1-alpha.2 | vX.Y.Z |
129+
130+
131+
# References
132+
The following may be useful references for those considering sio ports.
133+
* [Plan9 Audio](http://man.cat-v.org/plan_9/3/audio)
134+
* [PortAudio](http://portaudio.com)
135+
* [FreeBSD](https://www.freebsd.org/doc/handbook/sound-setup.html)
136+
* [ALSA](https://www.alsa-project.org/main/index.php/Main_Page)
137+
* [RtAudio](http://www.music.mcgill.ca/~gary/rtaudio/)
138+
* [Web Audio](https://www.w3.org/TR/webaudio/)
139+
* [Audio Units](https://developer.apple.com/documentation/audiounit?language=objc)
140+
* [VST](https://www.steinberg.net/en/company/technologies/vst3.html)
141+
* [Pulse Audio](https://en.wikipedia.org/wiki/PulseAudio)
142+
* [Android Audio](https://source.android.com/devices/audio/terminology)
143+
* [AudioFlinger](https://android.googlesource.com/platform/frameworks/av/+/109347d421413303eb1678dd9e2aa9d40acf89d2/services/audioflinger/AudioFlinger.cpp)
144+

‎README.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,113 @@
22

33
[![Build Status](https://travis-ci.com/zikichombo/sio.svg?branch=master)](https://travis-ci.com/zikichombo/sio)
44

5+
# Usage
6+
If you are using sio for sound capture and playback, only the [sio](http://godoc.org/zikichombo.org/sio)
7+
package is needed. For device scanning and APIs, the [host](http://godoc.org/zikichombo.org/sio/host)
8+
package provides the necessary support.
9+
10+
11+
# Ports
12+
For porting, see the [porting guide](Porting.md) and [contributing](Contributing.md).
13+
14+
## Status
15+
16+
Below is the status of sio ports. Items marked with an "X" in plain text (checked off
17+
in html rendered markdown) are incorporated into sio, potentially with alpha status.
18+
Items marked with a "?" indicates we do not yet have sufficient knowledge to judge
19+
whether or not the item is a TODO. Related discussion on the issue tracker is welcome.
20+
Items marked with "-" are those for which we think the functionality is not relevant or
21+
not sufficiently supported by the external software interface to add to sio.
22+
23+
In the event there are opinions about the content of the list itself, such as whether
24+
to support JACK, whether to interface with Android HAL, the issue tracker is our best
25+
means of coordinating the discussion.
26+
27+
28+
* Linux
29+
1. ALSA (cgo)
30+
1. [X] Playback
31+
1. [X] Capture
32+
1. [ ] Duplex
33+
1. [ ] Device Scanning
34+
1. [ ] Device Notification
35+
1. TinyALSA (cgo)
36+
1. [ ] Playback
37+
1. [ ] Capture
38+
1. [ ] Duplex
39+
1. [?] Device Scanning
40+
1. [?] Device Notification
41+
1. ALSA (no cgo)
42+
1. [?] Playback
43+
1. [?] Capture
44+
1. [?] Duplex
45+
1. [?] Device Scanning
46+
1. [?] Device Notification
47+
1. Pulse Audio
48+
1. [ ] Playback
49+
1. [ ] Capture
50+
1. [?] Duplex
51+
1. [?] Device Scanning
52+
1. [?] Device Notification
53+
* Darwin/iOS
54+
1. Audio Queue Services
55+
1. [X] Playback
56+
1. [X] Capture
57+
1. [-] Duplex
58+
1. [-] Device Scanning
59+
1. [ ] Test for iOS
60+
1. AUHAL
61+
1. [ ] Playback
62+
1. [ ] Capture
63+
1. [ ] Duplex
64+
1. [X] Device Scanning
65+
1. [ ] Test for iOS via RemoteIO replacing AUHAL.
66+
* Android
67+
1. TinyALSA
68+
1. [ ] Playback
69+
1. [ ] Capture
70+
1. [ ] Duplex
71+
1. [?] Device Scanning
72+
1. [?] Device Notification
73+
1. Android Audio HAL [?]
74+
1. AudioFlinger
75+
1. [ ] Playback
76+
1. [ ] Capture
77+
1. [?] Duplex
78+
1. [?] Device Scanning
79+
1. [?] Device Notification
80+
* Windows
81+
1. ASIO
82+
1. [?] Playback
83+
1. [?] Capture
84+
1. [?] Duplex
85+
1. [?] Device Scanning
86+
1. [?] Device Notification
87+
1. Direct Sound
88+
1. [?] Playback
89+
1. [?] Capture
90+
1. [?] Duplex
91+
1. [?] Device Scanning
92+
1. [?] Device Notification
93+
1. WASAPI
94+
1. [?] Playback
95+
1. [?] Capture
96+
1. [?] Duplex
97+
1. [?] Device Scanning
98+
1. [?] Device Notification
99+
* js
100+
1. Web Audio
101+
1. [ ] Playback
102+
1. [ ] Capture
103+
1. [-] Duplex
104+
1. [ ] Device Scanning
105+
1. [?] Device Notification
106+
107+
* plan9 [?]
108+
* netbsd [?]
109+
* freebsd [?]
110+
* openbsd [?]
111+
* dragonfly [?]
112+
113+
5114

‎aqin_darwin_test.go‎

Lines changed: 0 additions & 31 deletions
This file was deleted.

0 commit comments

Comments
 (0)