sfml.js 1.0.0-rc.2 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (314) hide show
  1. package/README.ja.md +16 -11
  2. package/README.ko.md +16 -11
  3. package/README.md +16 -11
  4. package/README.zh-CN.md +16 -11
  5. package/assets/breakout.png +0 -0
  6. package/binding.gyp +23 -16
  7. package/dist/audio/effect-processor.js +9 -3
  8. package/dist/audio/input-sound-file.js +41 -15
  9. package/dist/audio/listener.js +33 -11
  10. package/dist/audio/music.js +41 -18
  11. package/dist/audio/output-sound-file.js +4 -2
  12. package/dist/audio/playback-device.js +11 -3
  13. package/dist/audio/sound-buffer-recorder.js +8 -5
  14. package/dist/audio/sound-buffer.js +40 -17
  15. package/dist/audio/sound-file-factory.js +21 -9
  16. package/dist/audio/sound-file-reader.js +21 -7
  17. package/dist/audio/sound-recorder.js +36 -15
  18. package/dist/audio/sound-source.js +117 -40
  19. package/dist/audio/sound-stream.js +14 -5
  20. package/dist/audio/sound.js +9 -4
  21. package/dist/audio/value.js +42 -16
  22. package/dist/graphics/blend-mode.js +2 -1
  23. package/dist/graphics/boolean-vector.d.ts +1 -2
  24. package/dist/graphics/boolean-vector.js +19 -9
  25. package/dist/graphics/color.js +2 -1
  26. package/dist/graphics/convex-shape.js +7 -3
  27. package/dist/graphics/font.js +52 -23
  28. package/dist/graphics/glsl-matrix.js +8 -3
  29. package/dist/graphics/glsl.js +47 -16
  30. package/dist/graphics/glyph.js +27 -10
  31. package/dist/graphics/image.js +30 -14
  32. package/dist/graphics/rect.js +15 -8
  33. package/dist/graphics/render-states.js +18 -9
  34. package/dist/graphics/render-target.js +49 -23
  35. package/dist/graphics/render-texture.js +24 -12
  36. package/dist/graphics/render-window.js +6 -3
  37. package/dist/graphics/shader.js +67 -32
  38. package/dist/graphics/shape.js +25 -13
  39. package/dist/graphics/sprite.js +19 -9
  40. package/dist/graphics/stencil-mode.js +10 -6
  41. package/dist/graphics/swap.js +2 -1
  42. package/dist/graphics/text.js +123 -48
  43. package/dist/graphics/texture.js +48 -24
  44. package/dist/graphics/transform.js +29 -13
  45. package/dist/graphics/transformable.js +2 -1
  46. package/dist/graphics/vertex-array.js +40 -18
  47. package/dist/graphics/vertex-buffer.js +39 -19
  48. package/dist/graphics/vertex.js +6 -3
  49. package/dist/graphics/view.js +30 -14
  50. package/dist/index.d.ts +4 -4
  51. package/dist/internal/audio-codec-registry.js +12 -6
  52. package/dist/internal/audio-input-stream.js +2 -1
  53. package/dist/internal/audio-music-pump.js +58 -24
  54. package/dist/internal/audio-recorder-session.js +17 -7
  55. package/dist/internal/audio-worker-session.js +28 -10
  56. package/dist/internal/audio-worker.js +40 -21
  57. package/dist/internal/glsl-value.d.ts +3 -1
  58. package/dist/internal/glsl-value.js +18 -8
  59. package/dist/internal/graphics-state.js +29 -15
  60. package/dist/internal/input-stream.d.ts +3 -1
  61. package/dist/internal/input-stream.js +16 -7
  62. package/dist/internal/numeric-properties.js +2 -1
  63. package/dist/internal/render-states.js +2 -1
  64. package/dist/internal/scalar.js +22 -13
  65. package/dist/internal/shaped-glyph.d.ts +3 -1
  66. package/dist/internal/shaped-glyph.js +12 -4
  67. package/dist/internal/struct-view.d.ts +3 -1
  68. package/dist/internal/struct-view.js +3 -1
  69. package/dist/internal/transformable.js +2 -1
  70. package/dist/network/common.js +23 -11
  71. package/dist/network/dns.js +25 -17
  72. package/dist/network/ftp.js +43 -18
  73. package/dist/network/http.js +126 -56
  74. package/dist/network/ip-address.js +50 -25
  75. package/dist/network/packet.js +63 -25
  76. package/dist/network/sftp.js +175 -74
  77. package/dist/network/socket-selector.js +28 -14
  78. package/dist/network/socket.js +71 -30
  79. package/dist/network/tcp-listener.js +42 -19
  80. package/dist/network/tcp-socket.js +111 -53
  81. package/dist/network/tls-material.js +2 -1
  82. package/dist/network/udp-socket.js +68 -33
  83. package/dist/system/angle.js +2 -1
  84. package/dist/system/clock.js +4 -2
  85. package/dist/system/err.js +5 -2
  86. package/dist/system/file-input-stream.js +8 -4
  87. package/dist/system/input-stream.js +6 -3
  88. package/dist/system/operators.d.ts +1 -1
  89. package/dist/system/operators.js +90 -50
  90. package/dist/system/sleep.js +4 -2
  91. package/dist/system/time.js +12 -6
  92. package/dist/system/vector2.js +6 -7
  93. package/dist/system/vector3.js +11 -6
  94. package/dist/window/clipboard.js +2 -1
  95. package/dist/window/context.js +10 -5
  96. package/dist/window/cursor.js +2 -1
  97. package/dist/window/event.js +9 -5
  98. package/dist/window/mouse.js +4 -2
  99. package/dist/window/video-mode.js +2 -1
  100. package/dist/window/window.js +19 -12
  101. package/native/addon.cc +25 -12
  102. package/native/audio-binding.cc +266 -126
  103. package/native/audio-codec-binding.cc +147 -77
  104. package/native/audio-device-binding.cc +76 -49
  105. package/native/audio-file-binding.cc +116 -67
  106. package/native/audio-recorder-binding.cc +147 -98
  107. package/native/audio-recorder.h +1 -1
  108. package/native/audio-state.h +53 -30
  109. package/native/audio-stream-binding.cc +148 -94
  110. package/native/audio-stream.h +5 -4
  111. package/native/audio-worker-binding.cc +163 -81
  112. package/native/audio-worker.h +35 -19
  113. package/native/batch-drawable.cc +29 -16
  114. package/native/batch-drawable.h +11 -8
  115. package/native/context-binding.cc +40 -27
  116. package/native/context-settings.h +15 -8
  117. package/native/deferred-delete.cc +9 -6
  118. package/native/deferred-delete.h +7 -8
  119. package/native/error-stream-binding.cc +42 -28
  120. package/native/font-binding.cc +89 -48
  121. package/native/graphics-binding.cc +122 -72
  122. package/native/graphics-state.h +50 -36
  123. package/native/image-binding.cc +38 -24
  124. package/native/image-state.h +26 -18
  125. package/native/input-binding.cc +42 -27
  126. package/native/render-window-binding.cc +38 -23
  127. package/native/shader-binding.cc +115 -50
  128. package/native/shape-binding.cc +94 -49
  129. package/native/shape-state.h +18 -9
  130. package/native/shaped-glyph-storage.h +9 -5
  131. package/native/stream-binding.cc +143 -117
  132. package/native/system-binding.cc +17 -12
  133. package/native/text-binding.cc +68 -35
  134. package/native/text-state.h +25 -18
  135. package/native/texture-binding.cc +42 -33
  136. package/native/texture-resource.h +20 -12
  137. package/native/time-value.h +3 -1
  138. package/native/transformable-binding.cc +12 -6
  139. package/native/transformable-state.h +6 -6
  140. package/native/value-binding.h +46 -28
  141. package/native/value-layout.h +10 -10
  142. package/native/values-binding.cc +29 -23
  143. package/native/vertex-binding.cc +18 -12
  144. package/native/vertex-buffer-binding.cc +38 -24
  145. package/native/vertex-storage.h +2 -2
  146. package/native/view-data.h +4 -3
  147. package/native/window-binding.cc +75 -45
  148. package/native/window-event.h +20 -11
  149. package/native/window-owner.h +15 -12
  150. package/package.json +43 -50
  151. package/src/audio/effect-processor.ts +9 -3
  152. package/src/audio/input-sound-file.ts +108 -36
  153. package/src/audio/listener.ts +39 -13
  154. package/src/audio/music.ts +112 -47
  155. package/src/audio/output-sound-file.ts +40 -11
  156. package/src/audio/playback-device.ts +23 -8
  157. package/src/audio/sound-buffer-recorder.ts +35 -13
  158. package/src/audio/sound-buffer.ts +166 -58
  159. package/src/audio/sound-file-factory.ts +127 -49
  160. package/src/audio/sound-file-reader.ts +49 -15
  161. package/src/audio/sound-recorder.ts +100 -34
  162. package/src/audio/sound-source.ts +142 -45
  163. package/src/audio/sound-stream.ts +15 -5
  164. package/src/audio/sound.ts +12 -4
  165. package/src/audio/value.ts +89 -26
  166. package/src/graphics/blend-mode.ts +3 -1
  167. package/src/graphics/boolean-vector.ts +56 -26
  168. package/src/graphics/color.ts +3 -1
  169. package/src/graphics/convex-shape.ts +10 -3
  170. package/src/graphics/font.ts +171 -50
  171. package/src/graphics/glsl-matrix.ts +9 -3
  172. package/src/graphics/glsl.ts +81 -35
  173. package/src/graphics/glyph.ts +67 -26
  174. package/src/graphics/image.ts +119 -45
  175. package/src/graphics/rect.ts +56 -24
  176. package/src/graphics/render-states.ts +31 -14
  177. package/src/graphics/render-target.ts +197 -81
  178. package/src/graphics/render-texture.ts +36 -12
  179. package/src/graphics/render-window.ts +9 -3
  180. package/src/graphics/shader.ts +186 -61
  181. package/src/graphics/shape.ts +93 -35
  182. package/src/graphics/sprite.ts +64 -25
  183. package/src/graphics/stencil-mode.ts +12 -6
  184. package/src/graphics/swap.ts +3 -2
  185. package/src/graphics/text.ts +229 -74
  186. package/src/graphics/texture.ts +180 -61
  187. package/src/graphics/transform.ts +132 -47
  188. package/src/graphics/transformable.ts +3 -1
  189. package/src/graphics/vertex-array.ts +87 -35
  190. package/src/graphics/vertex-buffer.ts +97 -33
  191. package/src/graphics/vertex.ts +9 -3
  192. package/src/graphics/view.ts +59 -21
  193. package/src/index.ts +101 -23
  194. package/src/internal/audio-codec-registry.ts +18 -6
  195. package/src/internal/audio-input-stream.ts +6 -2
  196. package/src/internal/audio-music-pump.ts +116 -41
  197. package/src/internal/audio-native.ts +249 -96
  198. package/src/internal/audio-recorder-session.ts +68 -24
  199. package/src/internal/audio-worker-session.ts +65 -21
  200. package/src/internal/audio-worker.ts +85 -41
  201. package/src/internal/glsl-value.ts +26 -11
  202. package/src/internal/graphics-state.ts +57 -20
  203. package/src/internal/input-stream.ts +23 -10
  204. package/src/internal/native.ts +252 -99
  205. package/src/internal/numeric-properties.ts +2 -1
  206. package/src/internal/render-states.ts +3 -1
  207. package/src/internal/scalar.ts +33 -14
  208. package/src/internal/shaped-glyph.ts +25 -12
  209. package/src/internal/struct-view.ts +40 -13
  210. package/src/internal/transformable.ts +3 -1
  211. package/src/network/common.ts +35 -11
  212. package/src/network/dns.ts +95 -38
  213. package/src/network/ftp.ts +129 -47
  214. package/src/network/http.ts +232 -77
  215. package/src/network/ip-address.ts +118 -48
  216. package/src/network/packet.ts +161 -54
  217. package/src/network/sftp.ts +498 -168
  218. package/src/network/socket-selector.ts +66 -26
  219. package/src/network/socket.ts +133 -46
  220. package/src/network/tcp-listener.ts +78 -29
  221. package/src/network/tcp-socket.ts +240 -95
  222. package/src/network/tls-material.ts +6 -2
  223. package/src/network/udp-socket.ts +147 -53
  224. package/src/system/angle.ts +3 -1
  225. package/src/system/clock.ts +12 -4
  226. package/src/system/err.ts +5 -2
  227. package/src/system/file-input-stream.ts +12 -4
  228. package/src/system/input-stream.ts +9 -3
  229. package/src/system/operators.ts +290 -115
  230. package/src/system/sleep.ts +6 -2
  231. package/src/system/time.ts +18 -6
  232. package/src/system/timeout-with-predicate.ts +19 -8
  233. package/src/system/vector2.ts +101 -49
  234. package/src/system/vector3.ts +85 -36
  235. package/src/window/clipboard.ts +3 -1
  236. package/src/window/context.ts +15 -5
  237. package/src/window/cursor.ts +3 -1
  238. package/src/window/event.ts +26 -12
  239. package/src/window/mouse.ts +6 -2
  240. package/src/window/video-mode.ts +3 -1
  241. package/src/window/window.ts +119 -37
  242. package/test/native/audio-probes.cc +74 -36
  243. package/test/native/deferred-delete-probes.cc +17 -11
  244. package/test/native/drawable-probes.cc +70 -36
  245. package/test/native/exception-probes.cc +14 -9
  246. package/test/native/image-probes.cc +20 -10
  247. package/test/native/matrix-probes.cc +8 -4
  248. package/test/native/network-oracle.cc +17 -11
  249. package/test/native/render-texture-probes.cc +33 -24
  250. package/test/native/shader-probes.cc +9 -9
  251. package/test/native/shape-probes.cc +37 -23
  252. package/test/native/sprite-probes.cc +41 -25
  253. package/test/native/system-probes.cc +58 -35
  254. package/test/native/text-probes.cc +77 -44
  255. package/test/native/texture-probes.cc +43 -26
  256. package/test/native/time-probes.cc +18 -12
  257. package/test/native/transform-probes.cc +15 -10
  258. package/test/native/transformable-probes.cc +23 -17
  259. package/test/native/value-oracle.h +9 -4
  260. package/test/native/value-probes.cc +31 -23
  261. package/test/native/vertex-array-probes.cc +22 -14
  262. package/test/native/vertex-buffer-probes.cc +28 -17
  263. package/test/native/view-probes.cc +29 -17
  264. package/test/native/window-probes.cc +66 -33
  265. package/tools/ensure-sfml.cjs +9 -0
  266. package/tools/generate-network-constants.cjs +11 -6
  267. package/tools/generate-window-constants.cjs +31 -12
  268. package/docs/README.ja.md +0 -30
  269. package/docs/README.ko.md +0 -30
  270. package/docs/README.md +0 -30
  271. package/docs/README.zh-CN.md +0 -30
  272. package/docs/api.ja.md +0 -84
  273. package/docs/api.ko.md +0 -84
  274. package/docs/api.md +0 -81
  275. package/docs/api.zh-CN.md +0 -81
  276. package/docs/audio.ja.md +0 -249
  277. package/docs/audio.ko.md +0 -251
  278. package/docs/audio.md +0 -252
  279. package/docs/audio.zh-CN.md +0 -252
  280. package/docs/concepts.ja.md +0 -130
  281. package/docs/concepts.ko.md +0 -130
  282. package/docs/concepts.md +0 -131
  283. package/docs/concepts.zh-CN.md +0 -131
  284. package/docs/development.ja.md +0 -148
  285. package/docs/development.ko.md +0 -148
  286. package/docs/development.md +0 -150
  287. package/docs/development.zh-CN.md +0 -150
  288. package/docs/getting-started.ja.md +0 -154
  289. package/docs/getting-started.ko.md +0 -154
  290. package/docs/getting-started.md +0 -156
  291. package/docs/getting-started.zh-CN.md +0 -156
  292. package/docs/graphics.ja.md +0 -256
  293. package/docs/graphics.ko.md +0 -254
  294. package/docs/graphics.md +0 -255
  295. package/docs/graphics.zh-CN.md +0 -257
  296. package/docs/network.ja.md +0 -214
  297. package/docs/network.ko.md +0 -216
  298. package/docs/network.md +0 -218
  299. package/docs/network.zh-CN.md +0 -218
  300. package/docs/system.ja.md +0 -169
  301. package/docs/system.ko.md +0 -171
  302. package/docs/system.md +0 -173
  303. package/docs/system.zh-CN.md +0 -173
  304. package/docs/window.ja.md +0 -138
  305. package/docs/window.ko.md +0 -140
  306. package/docs/window.md +0 -141
  307. package/docs/window.zh-CN.md +0 -141
  308. package/native/exception-boundary.h +0 -97
  309. package/native/numeric-fields.h +0 -96
  310. package/native/shared-handle.h +0 -69
  311. package/test/tsconfig.json +0 -8
  312. package/tools/configure-lsp.cjs +0 -23
  313. package/tools/lib_downloader.cjs +0 -92
  314. package/tools/lib_downloader_urls.cjs +0 -23
package/docs/api.md DELETED
@@ -1,81 +0,0 @@
1
- # API Guide
2
-
3
- **English** · [简体中文](api.zh-CN.md) · [日本語](api.ja.md) · [한국어](api.ko.md)
4
-
5
- > sfml.js is based on SFML 3.1.0. The handwritten guides explain usage, return values and Node.js adaptations; [TypeDoc](https://sfml.js.org/reference/) generates complete signatures and type constraints from the source.
6
-
7
- [Documentation](README.md) · [Quick start](getting-started.md) · [Core concepts](concepts.md)
8
-
9
- Import all public APIs from `sfml.js`; see [src/index.ts](../src/index.ts) for the export list. Application code does not need to access `dist/internal` or native module handles.
10
-
11
- ## Choose by task
12
-
13
- | Task | Guide | Main APIs |
14
- | --- | --- | --- |
15
- | Calculate coordinates, angles and frame times | [System](system.md) | Vector2/3, Angle, Time, Clock, named operators |
16
- | Integrate custom file sources | [Input streams](system.md#input-streams) | InputStream, MemoryInputStream, FileInputStream |
17
- | Open windows and receive input | [Window](window.md) | RenderWindow, Window, Event, Keyboard, Mouse |
18
- | Display images and animation | [Graphics](graphics.md) | Image, Texture, Sprite |
19
- | Draw shapes and text | [Graphics](graphics.md) | Shape, Font, Glyph, Text |
20
- | Cameras, off-screen composition and batched geometry | [Graphics](graphics.md) | View, RenderTexture, VertexArray, VertexBuffer |
21
- | Custom drawing and shaders | [Graphics](graphics.md) | Drawable, RenderStates, Shader, Glsl |
22
- | Play, record and process audio | [Audio](audio.md) | SoundBuffer, Sound, Music, SoundStream, SoundRecorder |
23
- | Connect to networks and transfer files | [Network](network.md) | Packet, TcpSocket, UdpSocket, Http, Ftp, Sftp |
24
-
25
- ## System
26
-
27
- `Vector2`/`Vector3` support multiple scalar types; `Vector2i/u/f` and `Vector3i/u/f` are common specializations. `degrees()`/`radians()` create an Angle, and time factories create a Time.
28
-
29
- JavaScript does not support C++ operator overloading, so use `add()`, `multiply()`, `equal()` and `*Assign()` for the corresponding operations. This module also includes `Clock`, asynchronous `sleep()`, `TimeoutWithPredicate`, input streams, `Unicode` and error logging APIs.
30
-
31
- See [System](system.md).
32
-
33
- ## Window
34
-
35
- `Window` provides a system window and an OpenGL context. For 2D drawing, use `RenderWindow`, which combines Window and RenderTarget capabilities.
36
-
37
- Receive events through `pollEvent()`, `handleEvents()` or synchronous `waitEvent()`. Keyboard, mouse, joystick and sensor APIs also provide real-time queries. `Clipboard`, `Cursor`, `Context` and `Vulkan` cover system integration.
38
-
39
- See [Window](window.md).
40
-
41
- ## Graphics
42
-
43
- Image stores CPU-side pixels, Texture stores a GPU texture, and Sprite references a texture for drawing. Shape provides circles, rectangles, convex polygons and custom convex shapes; Font and Text provide font loading, layout and editable vertices.
44
-
45
- RenderTarget unifies drawing APIs for windows and off-screen targets. View controls the camera and viewport; RenderStates controls transforms, blending, stencil settings, textures and shaders. Vertex arrays and GPU vertex buffers let you organize geometry directly.
46
-
47
- See [Graphics](graphics.md) and [draw snapshots](concepts.md#draw-snapshots).
48
-
49
- ## Audio
50
-
51
- Use SoundBuffer + Sound for short effects and Music for long audio. SoundSource provides volume, panning and spatial audio properties; SoundStream, SoundRecorder and EffectProcessor use Worker callbacks to process custom data.
52
-
53
- See [Audio](audio.md), paying particular attention to sample counts, channel layout and buffer lifetime.
54
-
55
- ## Network
56
-
57
- Network implements SFML-style APIs using Node.js transports; production code does not call SFML C++ Network. Packet preserves SFML encoding conventions; TCP, UDP, DNS, TLS, HTTP, FTP and SFTP I/O use promises.
58
-
59
- See [Network](network.md) for returned statuses, partial sends, protocol limits and shutdown methods.
60
-
61
- ## Compatibility boundaries
62
-
63
- | Feature | Current behavior |
64
- | --- | --- |
65
- | C++ pointers and reference output parameters | Represented as objects, views or returned objects |
66
- | C++ templates and operators | Represented by explicit scalar tags, classes and named functions |
67
- | File loading | Uses promises, preserving each API's specific failure status |
68
- | Destruction | Native ownership works with JS references; explicitly close resources that expose a close method |
69
- | `drawAsync()`/`displayAsync()` | Not provided; legacy examples explicitly report them as unsupported |
70
- | Android SuspendAwareClock | Conditionally compiled API; the current download flow targets desktops |
71
- | Vulkan | Query APIs are exported; availability depends on the SFML platform backend, with no macOS backend |
72
-
73
- See the [development guide](development.md#testing) for platform build and test coverage.
74
-
75
- <a id="sfml-cpp-reference"></a>
76
-
77
- ## SFML C++ reference
78
-
79
- [TypeDoc](https://sfml.js.org/reference/) is the authority for JavaScript signatures and types. The [SFML 3.1.0 reference index](https://www.sfml-dev.org/documentation/3.1.0/) is the authority for upstream C++ concepts, not a drop-in JavaScript API reference.
80
-
81
- Each module guide links to relevant C++ classes and explains binding-specific differences: [System](system.md#sfml-cpp-reference), [Window](window.md#sfml-cpp-reference), [Graphics](graphics.md#sfml-cpp-reference), [Audio](audio.md#sfml-cpp-reference) and [Network](network.md#sfml-cpp-reference).
package/docs/api.zh-CN.md DELETED
@@ -1,81 +0,0 @@
1
- # API 导航
2
-
3
- [English](api.md) · **简体中文** · [日本語](api.ja.md) · [한국어](api.ko.md)
4
-
5
- > sfml.js 以 SFML 3.1.0 为基础。手写指南解释使用方式、返回值和 Node.js 适配;完整签名与类型约束由 [TypeDoc](https://sfml.js.org/zh/reference/) 从源码生成。
6
-
7
- [文档首页](README.zh-CN.md) · [快速开始](getting-started.zh-CN.md) · [核心概念](concepts.zh-CN.md)
8
-
9
- 所有公开接口均从 `sfml.js` 导入,导出清单见 [src/index.ts](../src/index.ts)。业务代码无需访问 `dist/internal` 或原生模块句柄。
10
-
11
- ## 按任务选择
12
-
13
- | 任务 | 文档 | 主要接口 |
14
- | --- | --- | --- |
15
- | 计算坐标、角度和帧时间 | [System](system.zh-CN.md) | Vector2/3、Angle、Time、Clock、具名运算符 |
16
- | 接入自定义文件来源 | [输入流](system.zh-CN.md#input-streams) | InputStream、MemoryInputStream、FileInputStream |
17
- | 打开窗口、接收输入 | [Window](window.zh-CN.md) | RenderWindow、Window、Event、Keyboard、Mouse |
18
- | 显示图片与动画 | [Graphics](graphics.zh-CN.md) | Image、Texture、Sprite |
19
- | 绘制形状与文字 | [Graphics](graphics.zh-CN.md) | Shape、Font、Glyph、Text |
20
- | 相机、离屏合成与批量几何 | [Graphics](graphics.zh-CN.md) | View、RenderTexture、VertexArray、VertexBuffer |
21
- | 自定义绘制与着色器 | [Graphics](graphics.zh-CN.md) | Drawable、RenderStates、Shader、Glsl |
22
- | 播放、录音及音频处理 | [Audio](audio.zh-CN.md) | SoundBuffer、Sound、Music、SoundStream、SoundRecorder |
23
- | 联网与传输文件 | [Network](network.zh-CN.md) | Packet、TcpSocket、UdpSocket、Http、Ftp、Sftp |
24
-
25
- ## System
26
-
27
- `Vector2`/`Vector3` 支持多种标量类型;`Vector2i/u/f` 和 `Vector3i/u/f` 是常用特化。`degrees()`/`radians()` 创建 Angle,时间工厂创建 Time。
28
-
29
- JavaScript 没有 C++ 运算符重载,对应操作使用 `add()`、`multiply()`、`equal()` 及 `*Assign()`。`Clock`、异步 `sleep()`、`TimeoutWithPredicate`、输入流、`Unicode` 和错误日志接口也属于本模块。
30
-
31
- 详见 [System](system.zh-CN.md)。
32
-
33
- ## Window
34
-
35
- `Window` 提供系统窗口及 OpenGL 上下文;二维绘制一般使用同时具有 Window 与 RenderTarget 能力的 `RenderWindow`。
36
-
37
- 事件可通过 `pollEvent()`、`handleEvents()` 或同步 `waitEvent()` 获取。键盘、鼠标、摇杆和传感器还提供实时查询。`Clipboard`、`Cursor`、`Context` 与 `Vulkan` 覆盖系统集成。
38
-
39
- 详见 [Window](window.zh-CN.md)。
40
-
41
- ## Graphics
42
-
43
- Image 保存 CPU 侧像素,Texture 保存 GPU 纹理,Sprite 引用纹理进行绘制。Shape 提供圆、矩形、凸多边形和自定义凸形状;Font 与 Text 提供字体加载、排版及可编辑顶点。
44
-
45
- RenderTarget 统一窗口和离屏目标的绘制接口。View 控制相机与视口,RenderStates 控制变换、混合、模板、纹理和 Shader。顶点数组及 GPU 顶点缓冲用于直接组织几何。
46
-
47
- 详见 [Graphics](graphics.zh-CN.md) 和 [绘制快照](concepts.zh-CN.md#draw-snapshots)。
48
-
49
- ## Audio
50
-
51
- 短音效使用 SoundBuffer + Sound,长音频使用 Music。SoundSource 提供音量、声像和空间音频属性;SoundStream、SoundRecorder、EffectProcessor 使用 Worker 回调处理自定义数据。
52
-
53
- 详见 [Audio](audio.zh-CN.md),特别注意样本数、声道排列及缓冲有效期。
54
-
55
- ## Network
56
-
57
- Network 使用 Node.js 传输实现 SFML 风格 API,生产代码不调用 SFML C++ Network。Packet 保留 SFML 编码约定;TCP、UDP、DNS、TLS、HTTP、FTP 和 SFTP 的 I/O 使用 Promise。
58
-
59
- 详见 [Network](network.zh-CN.md),包括状态返回、部分发送、协议限制与关闭方式。
60
-
61
- ## 兼容边界
62
-
63
- | 项目 | 当前行为 |
64
- | --- | --- |
65
- | C++ 指针、引用输出参数 | 用对象、视图或返回对象表达 |
66
- | C++ 模板及运算符 | 用明确的标量标签、类和具名函数表达 |
67
- | 文件加载 | 使用 Promise,具体失败状态按接口保留 |
68
- | 析构 | Native 所有权配合 JS 引用;有关闭接口的资源应显式关闭 |
69
- | `drawAsync()`/`displayAsync()` | 未提供,旧示例明确报告不支持 |
70
- | Android SuspendAwareClock | 有条件编译接口;当前下载流程面向桌面 |
71
- | Vulkan | 已导出查询接口;可用性取决于 SFML 平台后端,macOS 后端不可用 |
72
-
73
- 平台构建与测试范围见 [开发指南](development.zh-CN.md#testing)。
74
-
75
- <a id="sfml-cpp-reference"></a>
76
-
77
- ## SFML C++ 参考
78
-
79
- [SFML 3.1.0 官方文档](https://www.sfml-dev.org/documentation/3.1.0/) 解释 C++ 类和上游概念,TypeDoc 则是 sfml.js 的 JavaScript/TypeScript 签名参考。两者配合阅读:先用上游文档理解功能,再按本项目指南调用。
80
-
81
- 各模块的上游链接与适配边界:[System](system.zh-CN.md#sfml-cpp-reference)、[Window](window.zh-CN.md#sfml-cpp-reference)、[Graphics](graphics.zh-CN.md#sfml-cpp-reference)、[Audio](audio.zh-CN.md#sfml-cpp-reference)、[Network](network.zh-CN.md#sfml-cpp-reference)。
package/docs/audio.ja.md DELETED
@@ -1,249 +0,0 @@
1
- # Audio
2
-
3
- [English](audio.md) / [简体中文](audio.zh-CN.md) / **日本語** / [한국어](audio.ko.md)
4
-
5
- > 短い効果音には SoundBuffer + Sound、長い音声には Music を使います。独自のデータ供給、録音処理、エフェクトは Node Worker で実行します。
6
-
7
- [API ナビゲーション](api.ja.md) · [基本概念](concepts.ja.md) · [サンプル](../examples/README.ja.md)
8
-
9
- ## インターフェースの選択
10
-
11
- | 目的 | インターフェース |
12
- | --- | --- |
13
- | 短い効果音を読み込んで繰り返し再生 | SoundBuffer、Sound |
14
- | ファイル、メモリ、入力ストリームのストリーミング再生 | Music |
15
- | PCM を独自に生成 | SoundStream + Worker モジュール |
16
- | 音量、パン、空間プロパティの調整 | SoundSource、Listener |
17
- | 再生デバイスの選択 | PlaybackDevice |
18
- | バッファへの録音 | SoundBufferRecorder |
19
- | 収録データの独自処理 | SoundRecorder + Worker モジュール |
20
- | 音源出力の処理 | EffectProcessor |
21
- | 音声ファイルの読み書きと形式の拡張 | InputSoundFile、OutputSoundFile、SoundFileFactory |
22
-
23
- ファイルと圧縮データには「空のコンストラクター + await open/load」を使います。SoundBuffer と Sound はコピーコンストラクターを提供し、SoundBuffer は PCM からの構築にも対応します。完全なシグネチャは [TypeDoc](https://sfml.js.org/ja/reference/) を参照してください。
24
-
25
- ## 短い効果音の再生
26
-
27
- ```js
28
- const sf = require('sfml.js');
29
-
30
- async function play() {
31
- const buffer = new sf.SoundBuffer();
32
- if (!await buffer.loadFromFile('sound.wav')) {
33
- throw new Error('Cannot load sound.wav');
34
- }
35
- const sound = new sf.Sound(buffer);
36
- sound.setVolume(25);
37
- sound.play();
38
- while (sound.getStatus() === sf.SoundStatus.Playing) {
39
- await sf.sleep(sf.milliseconds(10));
40
- }
41
- }
42
- play().catch(error => {
43
- console.error(error);
44
- process.exitCode = 1;
45
- });
46
- ```
47
-
48
- `setLooping()` でループを制御し、`setPlayingOffset()` で再生位置を調整します。複数の Sound は同じ SoundBuffer を共有できます。Sound をコピーしても Worker のエフェクトは共有しません。
49
-
50
- ## 音楽の再生
51
-
52
- 以下のコードは async 関数内で実行してください。
53
-
54
- ```javascript
55
- const music = new sf.Music();
56
- try {
57
- if (!await music.openFromFile('music.ogg')) {
58
- throw new Error('Cannot open music.ogg');
59
- }
60
- music.play();
61
- await sf.sleep(sf.seconds(5));
62
- } finally {
63
- await music.close();
64
- }
65
- ```
66
-
67
- Music は SoundStream を継承し、再生時間とループ区間を提供します。getter が返した Time を読み取っても、再生位置を直接変更することはできません。変更には setter を呼ぶ必要があります。
68
-
69
- ## PCM と共有メモリ
70
-
71
- `getSamples()` は `sf::SoundBuffer::getSamples()` にマッピングされた Int16Array を返し、空のバッファでは undefined を返します。音声サンプルはチャンネルをインターリーブして配置します。sampleCount は全チャンネルを含むサンプル数で、bigint を使います。サンプルレートとチャンネル数は number、duration と playingOffset は Time を使います。
72
-
73
- SoundBuffer の sampleRate と duration は安定した SFML フィールドに直接マッピングされ、サンプル数とチャンネル数はネイティブ側の派生フィールドに保存されます。Cone、TimeSpan、SoundFileReader.Info の数値は、それぞれのネイティブ構造体にマッピングされます。SoundSource と Listener は、安定したネイティブの数値制御領域を使って引数と結果を受け渡します。各制御操作では引き続き SFML の setter/getter を呼び、オーディオエンジンが同期、変換、状態更新を行います。位置、方向、Cone、Time は独立した値を返すため、getter の結果を変更しても音源は変わりません。
74
-
75
- PCM と読み取り専用の channelMap ビューの BackingStore は、対応するネイティブメモリの割り当てを維持します。SoundBuffer の再読み込みが成功すると、古いビューは古い割り当てを指し続け、関連する Sound は新しいバッファに切り替わります。読み込みに失敗した場合は現在のリソースを保持します。SoundBufferRecorder は録音ごとに新しいネイティブ recorder を使い、終了時にはその `getBuffer()` を直接マッピングします。以前の録音のビューも引き続き有効です。
76
-
77
- `new SoundBuffer(samples, channelCount, sampleRate, channelMap)` は Int16Array から同期的に構築します。配列ビューの長さをサンプル数として使い、SFML がサンプルをコピーします。読み込みに失敗すると SFMLError を投げます。
78
-
79
- `target.assign(source)` は source の現在のサンプルとメタデータをネイティブ側でディープコピーし、target を返します。転送先の JS オブジェクトとネイティブハンドルは変わらず、関連する Sound は転送先の新しい割り当てに再バインドされます。以前に取得したサンプルとチャンネルのビューは古い割り当てを維持します。source には録音が返す ReadonlySoundBuffer も使えます。自己代入は直ちに返り、ビューや再生状態を変更しません。このメソッドと `loadFromSamples()` は現在のリソースを同期的に置き換えますが、すでに開始済みの非同期読み込みが成功すると、その結果も後から反映されます。操作順序を固定したい場合は、先に読み込みを await してください。
80
-
81
- ```js
82
- const source = new sf.SoundBuffer(
83
- new Int16Array([ 1000, -1000, 500, -500 ]),
84
- 1, 44100, [ sf.SoundChannel.Mono ],
85
- );
86
- const target = new sf.SoundBuffer();
87
- target.assign(source);
88
- ```
89
-
90
- ReadonlySamples、ChannelMap、ReadonlySoundBuffer の読み取り専用制約は TypeScript の型に適用されます。実行時にサンプルごとの Proxy はありません。JS から無理に書き込んだり、これらの読み取り専用ビューの基盤 buffer を切り離したり転送したりしないでください。独立した書き込み可能なデータが必要な場合は `slice()` を使います。
91
-
92
- `loadFromSamples()` は SFML を同期的に呼び、SFML がコピー済みのサンプルを保持します。非同期のメモリ読み込みとファイルの read/write は、操作に関わる基盤メモリの割り当てを保持します。呼び出し側は Promise が完了するまで、入力/出力バッファを変更、切り離し、リサイズしてはいけません。`Music.openFromMemory()` と `InputSoundFile.openFromMemory()` の圧縮データは、リソースを閉じるか開き直すまで変更しないでください。
93
-
94
- ## 音源のコピー代入
95
-
96
- `SoundSource.assign(source)` は、ピッチ、パン、音量、空間化、位置、方向、音響コーン、速度、ドップラー、指向性減衰係数、相対位置モード、距離、ゲイン、減衰の設定を同期的にコピーし、転送先自身を返します。Music と独自の SoundStream はこのメソッドを継承します。転送先の内容、ループ設定、再生位置、再生状態、エフェクトは保持され、コピー元には影響しません。コピーは 1 回のネイティブ呼び出しで完了し、SFML の setter がエンジンを更新します。制御領域の fast buffer は元のマッピングを維持します。
97
-
98
- `Sound.assign(sourceSound)` は Sound を受け取り、上記のプロパティ、ループ設定、SoundBuffer のバインドを同期的にコピーします。2 つの Sound は同じバッファを参照し、代入は JS 参照、ネイティブ側の寿命維持、関連付けリストを更新します。転送先は停止して再生位置がゼロに戻り、コピー元の再生は変わりません。転送先は自身の EffectProcessor を保持します。既存のエフェクトキューは世代番号の更新によって無効化され、その後、古いブロックが破棄されます。転送先のネイティブ sf::Sound インスタンスと制御領域は変わりません。
99
-
100
- どちらの assign も、自己代入では直ちに返ります。Sound に対して基底クラスのプロパティだけをコピーしたい場合は、`SoundSource.prototype.assign.call(targetSound, source)` を明示的に呼べます。変数の型を SoundSource としても、JS の動的なメソッドディスパッチは変わりません。
101
-
102
- SFML 3.1.0 の `SoundSource::operator=` は directionalAttenuationFactor をコピーしませんが、このバインディングのプロパティコピーにはこのフィールドも含まれます。
103
-
104
- ```js
105
- music.assign(sound); // 音源プロパティをコピーし、music の内容と再生状態は保持する。
106
- targetSound.assign(sourceSound); // 同じバッファにバインドし、targetSound を停止して再生位置をゼロに戻す。
107
- ```
108
-
109
- ## Worker によるデータ供給
110
-
111
- すべての Audio Worker はモジュールのファクトリーを使い、CommonJS と ESM に対応します。`module` はファイルパスまたは URL、`exportName` の既定値は `default` です。`data` は Worker の structured clone 規則に従って渡されます。ファクトリーは `{ sampleRate, channelCount, blockFrames }` と data を受け取り、対応するコールバックオブジェクトを返します。Promise を返すこともできます。
112
-
113
- リポジトリの [audio-worker.cjs](../examples/audio-worker.cjs) には、実行可能な `tone` と `filter` のファクトリーがあります。
114
-
115
- ```js
116
- const path = require('node:path');
117
- const sf = require('sfml.js');
118
-
119
- async function playStream() {
120
- const stream = new sf.SoundStream({
121
- module: path.resolve('examples/audio-worker.cjs'),
122
- exportName: 'tone',
123
- data: { frequency: 330 },
124
- sampleRate: 44100,
125
- channelCount: 1,
126
- channelMap: [ sf.SoundChannel.Mono ],
127
- blockFrames: 1024,
128
- queueBlocks: 8,
129
- });
130
- try {
131
- if (!await stream.ready) return;
132
- stream.play();
133
- await sf.sleep(sf.seconds(2));
134
- } finally {
135
- await stream.close();
136
- }
137
- }
138
- playStream().catch(error => {
139
- console.error(error);
140
- process.exitCode = 1;
141
- });
142
- ```
143
-
144
- | コールバック | 契約 |
145
- |------|------|
146
- | `onGetData(chunk)` | ネイティブ側が提供する `chunk.samples` に書き込み、`chunk.sampleCount` を設定する。true は継続、false は最後のブロックを意味する |
147
- | `onSeek(time)` | 生成側のカーソルを Time に移動する。初期化時にも 1 回呼ばれる |
148
- | `onLoop()` | 最後のブロックの準備段階で呼ばれる。インターリーブされたサンプルのオフセットを bigint で返し、undefined は今回のループを禁止する。省略時は既定で `0n` を返す |
149
- | `onClose()` | Worker の終了前にリソースをクリーンアップする |
150
-
151
- `chunk.samples` を置き換えることはできません。sampleCount はスロットの容量を超えてはならず、チャンネル数の整数倍である必要があります。データ供給を続ける場合は、ゼロサンプルを送信できません。最後のブロックには有効なサンプルを含められます。seek 時にネイティブ側が世代番号を更新し、デバイススレッドが以前にキューへ入れたデータを破棄します。その後 Worker が新しい onSeek を実行します。
152
-
153
- コールバックが受け取る TypedArray は、再利用可能なネイティブスロットです。そのコールバックが完了するまでの間だけ、そのコールバックが専有します。保持して後からアクセスしないでください。内容を残す必要がある場合は自身で `slice()` します。Promise が完了して初めてスロットが送信または解放されます。コールバックは必ず最終的に完了する必要があります。完了しないユーザー Promise は、正常な `close()` や録音キューの排出を妨げます。
154
-
155
- ## エフェクト
156
-
157
- 以下のコードは、作成済みの Sound に続けて async 関数内で実行します。`path` は `node:path` を指し、Worker モジュールのパスはリポジトリのルートを基準とします。
158
-
159
- ```js
160
- const effect = new sf.EffectProcessor({
161
- module: path.resolve('examples/audio-worker.cjs'),
162
- exportName: 'filter',
163
- blockFrames: 1024,
164
- queueBlocks: 8,
165
- maxChannelCount: 8,
166
- });
167
- await effect.ready;
168
- sound.setEffectProcessor(effect);
169
- // 使用後は、先に音源から取り外してから Worker を終了する。
170
- sound.setEffectProcessor();
171
- await effect.close();
172
- ```
173
-
174
- エフェクトのファクトリーは `process(input, inputFrameCount, output, outputFrameCount, channelCount)` を返します。input と output はネイティブの float32 キューへのマッピングです。入力はすでに空間化されており、channelCount は今回のデバイス出力のチャンネル数です。`{ inputFrameCount, outputFrameCount }` を返して実際に消費・生成したフレーム数を指定でき、部分的な消費も可能です。void を返すと、入力をすべて消費し、同じフレーム数を出力したものとみなします。残響処理以外の呼び出しでは、少なくとも 1 フレームを消費または生成する必要があります。
175
-
176
- input が null の場合は残響処理を表します。残響を出力でき、最後に出力フレーム数としてゼロを返すと終了します。各フレームは channelCount 個のインターリーブされた float32 サンプルを持ち、今回渡された有効なビューの範囲だけにアクセスできます。`maxChannelCount` は事前割り当ての容量で、既定値は 8 です。実際のチャンネル数が容量を超えると無音を出力します。ファクトリーの context 内の channelCount は容量を表し、実際の処理では process の引数を基準とします。sampleRate は Worker の作成時に読み取るため、デバイスの切り替え後には、サンプルレートに依存するエフェクトを作り直す必要があります。
177
-
178
- 1 つの EffectProcessor を同時に取り付けられる音源は 1 つだけです。取り外した後は別の音源に取り付けられます。取り付けと取り外しは、音源の再生位置と再生/一時停止状態を保持します。取り付けたままの EffectProcessor を明示的に閉じると、その音源のエフェクト経路は無音を出力します。
179
-
180
- ## 録音
181
-
182
- 以下のコードは async 関数内で実行し、`sf` はパッケージのインポートを指します。先に入力デバイスが利用できることを確認し、OS のマイク権限を許可してください。
183
-
184
- ```js
185
- const recorder = new sf.SoundBufferRecorder();
186
- recorder.setChannelCount(1);
187
- try {
188
- if (!await recorder.start(44100)) throw new Error('Cannot start recording');
189
- await sf.sleep(sf.seconds(1));
190
- } finally {
191
- await recorder.stop();
192
- }
193
- const recorded = recorder.getBuffer();
194
- console.log(recorded.getSampleCount());
195
- if (!await recorded.saveToFile('recorded.wav')) throw new Error('Cannot save recording');
196
- ```
197
-
198
- `start()`、`stop()`、`setDevice()` は Promise を返します。チャンネル数は 1 または 2 に対応します。変更する前に録音を停止し、処理中の操作を待ってください。再生デバイスと入力デバイスは別々に照会・選択します。
199
-
200
- 独自の SoundRecorder は SoundStream と同じ Worker 設定を使います。ファクトリーは任意の `onStart()`、必須の `onProcessSamples(samples)`、任意の `onStop()` を返します。onStart が false を返すと開始を取り消します。onProcessSamples はコールバック中だけ有効なネイティブの Int16Array を受け取ります。false を返すと非同期タスクが収録を停止します。通常の `await stop()` はキューの排出と onStop の完了を待ちますが、コールバックが自ら false を返した場合は、キュー内の残りのサンプルを破棄します。
201
-
202
- ## ファイルストリームとコーデックの拡張
203
-
204
- SoundBuffer、Music、InputSoundFile は、既存の InputStream、MemoryInputStream、FileInputStream に対応しています。ファイルの読み書き、開く操作、閉じる操作はオブジェクト単位で直列に実行し、異なるオブジェクト間では並列に実行できます。開く操作が成功してからネイティブのメタデータを公開します。非同期の read/seek が完了するまで、getter は前回公開された結果を返します。
205
-
206
- SFML 内蔵のファイル/メモリのデコードはスレッド内で実行します。非同期 InputStream は、独立したネイティブのデコードスレッドと libuv 通知のブリッジを使い、JS のファイル I/O を待つことで libuv のワーカースレッドプールを占有し尽くすのを防ぎます。InputStream の read の書き込み先バッファはネイティブ側で割り当て、完了時に有効なバイト列のスナップショットを取得します。
207
-
208
- Music の通常のファイル/メモリ入力は `sf::Music` を使います。InputStream または登録済みの JS Reader からの入力は、容量を制限した PCM プリフェッチを使い、既定は 1024 フレーム、8 スロットです。非同期デコードはデバイスコールバックの外で実行し、再生、シーク、ループはネイティブの SoundStream を通じてデータを消費します。JS のカスタム Reader は呼び出し元の環境で動作するため、時間のかかる同期的な JS デコードは、その環境のイベントループを占有します。
209
-
210
- SFML 内蔵の Reader/Writer は、SoundFileFactory で作成した後も `open()` を呼ぶ必要があります。WAV、FLAC、Ogg の書き込みと読み戻しにはランタイムテストがあります。その他の SFML 内蔵入力形式は、現在の SFML ビルドが提供するデコード対応を引き継ぎます。
211
-
212
- 拡張 Reader は SoundFileReader を継承し、静的な `check(stream)`、`open(stream)`、`seek(sampleOffset)`、`read(samples)`、任意の `close()` を提供します。open は `new SoundFileReader.Info({ sampleCount, sampleRate, channelCount, channelMap })` または undefined を返します。read は渡された Int16Array に書き込み、実際のサンプル数を bigint で返します。拡張 Writer は SoundFileWriter を継承し、静的な `check(filename)`、`open(filename, sampleRate, channelCount, channelMap)`、`write(samples)`、任意の `close()` を提供します。これらのメソッドは Promise を返せます。
213
-
214
- `SoundFileFactory.registerReader(ReaderClass)` と `registerWriter(WriterClass)` で登録し、対応する unregister メソッドで解除します。同じクラスを繰り返し登録しても重複して追加されません。JS のレジストリーは現在の Node 環境に属するため、Worker は自身の環境で登録する必要があります。すべての公開 SoundBuffer、Music、音声ファイルの入口は、登録済みの JS クラスを先に調べ、一致しなければ SFML 内蔵のファクトリーにフォールバックします。テンプレートによる登録インターフェースは JS クラスで実現し、プロセス全体の C++ ファクトリーへ JS の関数ポインターを組み込むことはありません。完全な拡張例は [audio-codec.test.cjs](../test/audio-codec.test.cjs) を参照してください。
215
-
216
- ## バッファ、状態、クリーンアップ
217
-
218
- Worker の既定値は `blockFrames = 1024`、`queueBlocks = 8` です。64~65536 フレーム、2~32 スロット、1~32 チャンネルを指定できます。スロットのメモリはネイティブ側で事前に割り当て、acquire/release によって公開と返却を行います。PCM を postMessage でコピーすることはありません。postMessage は ready、エラー、停止の通知だけを伝えます。
219
-
220
- 44100 Hz の 1024 フレームは 23.22 ms で、8 スロットには約 185.76 ms のサンプルを格納できます。これはブロックの長さとキューの容量であり、エンドツーエンドの遅延を保証する値ではありません。Worker は 2 ms ごとに利用可能なスロットを非同期で確認します。デバイスの出力は SFML とシステムのバッファにも影響されます。
221
-
222
- | 状況 | 挙動と統計の単位 |
223
- |------|----------------|
224
- | Stream に準備済みの PCM がない | 無音を出力。underruns はブロック不足の回数を集計 |
225
- | 録音キューが満杯 | 新しいサンプルを破棄。overruns はインターリーブされたサンプル数を集計 |
226
- | エフェクトの入力キューが満杯 | 今回受信した入力フレームを破棄。overruns はフレーム数を集計 |
227
- | エフェクトの出力が不足 | 不足部分を無音で補う。underruns はフレーム数を集計 |
228
- | processed | Stream/Recorder はインターリーブされたサンプル数、EffectProcessor は消費した入力フレーム数 |
229
-
230
- `getWorkerStats()` は bigint の統計スナップショットを、`getWorkerError()` は記録済みの非同期エラーを返します。Worker の初期化エラーは ready を reject させ、close/stop も Worker のエラーを報告します。C++ の例外は SFMLError にマッピングされ、SFML の診断は既存の `err()`/`setErrorOutput()` 経路に出力されます。
231
-
232
- Audio Worker は初期化が完了すると unref され、それだけでは Node プロセスを存続させません。再生中はウィンドウループや `await sleep()` でイベントループを維持してください。終了時には `await stream.close()`、`await music.close()`、`await effect.close()`、`await recorder.stop()` を使います。ファイル書き込みは `await output.close()` で末尾処理とリソースのクリーンアップを完了します。ネイティブの音源と録音リソースは、プロジェクトのバックグラウンド解放機構を引き継ぎます。ビューは対応する割り当てを維持し、Node 環境の終了時には、その環境に属するリソースが終了します。
233
-
234
- 再生デバイスの通知は、コールバックを登録した JS スレッドへ非同期で配送され、オーディオデバイスのスレッドでは実行されません。SFML の通知コールバックはプロセス単位の単一スロットであり、最後の登録が以前の登録を置き換えます。`setNotificationCallback()` を呼ぶと登録を解除し、未配送の通知を破棄します。
235
-
236
- ## デモと検証
237
-
238
- `npm run demo:audio`、またはビルド後に `node examples/audio.cjs` を実行します。1~4 で Sound、WorkerStream、Music、録音再生を切り替えます。Space は再生/一時停止、S は停止、E はエフェクトの切り替え、R は録音開始、T は録音終了です。矢印キーでパンと音量を操作し、Esc で閉じます。録音はメモリ内だけに保持します。
239
-
240
- `node examples/audio.cjs --smoke --frames=90` は、スピーカー再生、Worker PCM、エフェクト処理、Music、マイク録音と再生を自動的に検証してから終了します。このモードはローカルの入力デバイスを有効にします。通常起動ではユーザーのキー入力を待ちます。
241
-
242
- 自動テストは、SFML フィールドとの比較、PCM ビュー、リソースのライフサイクル、WAV/FLAC/Ogg、非同期入力ストリーム、Worker のデータ供給とシーク、エフェクト、録音キュー、独自のコーデックを対象としています。テストコードは [test/audio.test.cjs](../test/audio.test.cjs)、[Worker テスト](../test/audio-worker.test.cjs)、[コーデックテスト](../test/audio-codec.test.cjs)を参照してください。
243
-
244
- 実際の音声出力、マイク収録、デバイスのホットプラグは対象デバイスで検証する必要があります。CI のビルドとテスト設定は[開発ガイド](development.ja.md#testing)を参照してください。
245
-
246
- <a id="sfml-cpp-reference"></a>
247
- ## SFML C++ リファレンス
248
-
249
- 上流の [SoundBuffer](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1SoundBuffer.html)、[Sound](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Sound.html)、[Music](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Music.html)、[SoundStream](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1SoundStream.html)、[SoundRecorder](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1SoundRecorder.html)、[SoundFileFactory](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1SoundFileFactory.html) で、再生、空間オーディオ、音声ファイルの概念を確認できます。JS の非同期リソースメソッド、Worker コールバック、共有バッファの寿命は C++ と異なるため、このガイドの契約を優先してください。