1212![ Forks] ( https://img.shields.io/github/forks/krotname/JavaSoundRecorder )
1313![ Java] ( https://img.shields.io/badge/Java-21-007396 )
1414
15- A production-style Java desktop reference project showing a clean audio recording pipeline: capture -> orchestration -> upload strategy -> UI or CLI .
15+ JavaSoundRecorder — Java 21 desktop-проект для записи звука с микрофона, демонстрирующий аккуратную архитектуру, воспроизводимую сборку, многоуровневые тесты, CI, coverage и supply-chain quality gates .
1616
17- ** Read this in** : [ English] ( #english ) · [ Русский] ( #русский )
18-
19- ## English
20-
21- ### What this repo demonstrates
22-
23- - Strong package boundaries (` config ` , ` audio ` , ` orchestration ` , ` storage ` , ` ui ` )
24- - Deterministic CLI and Swing demo mode
25- - Reproducible Maven Wrapper setup (` ./mvnw ` / ` mvnw.cmd ` )
26- - Environment-driven configuration
27- - CI gates: tests, checkstyle, SpotBugs, CodeQL, dependency hygiene, coverage
28- - GitHub Actions workflow linting with actionlint
29- - Current stable dependency baseline with documented update policy
30- - Multi-category tests (unit/integration/ui, plus contract checks and architecture rules)
31- - Explicit quality policy, release automation, and artifact attestations
32- - Issue triage templates for bug reports and feature requests
33-
34- ### Architecture at a glance
35-
36- ``` mermaid
37- flowchart LR
38- Env[Environment Config\nAppConfig]
39- Main[Main\nbootstrap]
40- Capture[JavaSoundCaptureService\naudio pipeline]
41- Cohesion[RecordingCoordinator\norchestration]
42- Upload[Storage Strategy\n(UploadService)]
43- UI[RecorderPanel\nSwing UI]
44-
45- Env --> Main
46- Main --> Cohesion
47- Main --> UI
48- Capture --> Cohesion
49- Upload --> Cohesion
50- Cohesion --> UI
51- UI --> Cohesion
52- ```
53-
54- ### Features
55-
56- - ** Default one-shot workflow** : records once for ` JAVASOUNDRECORDER_RECORDING_DURATION_MS ` and uploads (when enabled).
57- - ** Upload abstraction** : ` UploadService ` strategy (Dropbox, local disk fallback, noop).
58- - ** Defensive configuration** : strict booleans, normalized Dropbox paths, blank-value fallbacks.
59- - ** Safe concurrent behavior** : async orchestration with single-flight guard, cancel support, and lifecycle cleanup.
60- - ** UI workflow** : ` Start/Stop ` , status labels, run-state lock, and EDT-safe async updates.
61- - ** Observability** : structured logs and strict test naming convention.
62-
63- ### Quickstart
64-
65- ``` bash
66- git clone https://github.com/krotname/JavaSoundRecorder.git
67- cd JavaSoundRecorder
68- ./mvnw clean verify
69- ```
70-
71- On Windows, use ` mvnw.cmd ` instead of ` ./mvnw ` .
72-
73- #### Run CLI
74-
75- ``` bash
76- ./mvnw -q exec:java
77- ```
78-
79- Defaults: ` 60000 ` (milliseconds) and recordings folder ` ~/JavaSoundRecorder/recordings ` .
80-
81- ``` bash
82- ./mvnw -q exec:java \
83- -Dexec.mainClass=com.krotname.javasoundrecorder.Main \
84- -Dexec.args=" --ui"
85- ```
86-
87- #### Docker
88-
89- ``` bash
90- ./mvnw -q package
91- docker build -t javasoundrecorder .
92- docker run --rm javasoundrecorder
93- ```
94-
95- ### Configuration
96-
97- | Environment variable | Purpose |
98- | ---| ---|
99- | ` JAVASOUNDRECORDER_RECORDING_DURATION_MS ` | recording duration in milliseconds |
100- | ` JAVASOUNDRECORDER_RECORDING_DIRECTORY ` | output folder for WAV files |
101- | ` DROPBOX_ACCESS_TOKEN ` | Dropbox API token |
102- | ` JAVASOUNDRECORDER_DROPBOX_UPLOAD_FOLDER ` | remote folder path |
103- | ` JAVASOUNDRECORDER_UPLOAD_ENABLED ` | explicit enable flag (` true/false ` ) |
104-
105- Invalid boolean values fail fast. Dropbox upload folders are normalized to absolute Dropbox paths.
106-
107- ### Demo surface
108-
109- ![ JavaSoundRecorder Swing UI] ( assets/screenshot-ui.png )
110- To refresh this screenshot after a UI change, run ` ./mvnw -q -Dexec.mainClass=com.krotname.javasoundrecorder.Main -Dexec.args="--ui" ` and capture it from the opened demo.
111-
112- ### Test strategy
113-
114- - ` *UnitTest ` — pure in-memory behavior and branching.
115- - ` *IntegrationTest ` — cross-layer behavior with temp directories and real I/O.
116- - ` *UiTest ` — Swing component behavior and event-dispatch-thread safety.
117- - ` *SmokeTest ` / ` *ContractTest ` — minimal production-path checks for public API and transport assumptions.
118- - ` ArchitectureUnitTest ` — package-cycle guard and no UI-driven dependency drift checks.
119-
120- Run explicitly by category:
121-
122- ``` bash
123- ./mvnw -q -Dtest=* UnitTest test
124- ./mvnw -q -Dtest=* IntegrationTest test
125- ./mvnw -q -Dtest=* UiTest test
126- ./mvnw -q -Dtest=' *SmokeTest,*ContractTest' test
127- ./mvnw -q -Dtest=ArchitectureUnitTest test
128- ```
129-
130- Coverage and quality gate:
131-
132- ``` bash
133- ./mvnw -q verify
134- ```
135-
136- This enforces configured line/branch thresholds in ` pom.xml ` .
137-
138- ### Repository quality surface
139-
140- - ` .github/workflows/ci.yml ` : CI with unit/integration/ui/contract/smoke/architecture tests, coverage gate, checkstyle, SpotBugs, and dependency review.
141- - ` .github/workflows/actionlint.yml ` : static validation for GitHub Actions workflow files.
142- - Maven Wrapper: reproducible local and CI builds via Maven 3.9.16.
143- - GitHub Actions hardening: scoped token permissions, job timeouts, concurrency controls, and non-persistent checkout credentials.
144- - GitHub Actions are pinned to immutable commit SHAs; Docker images are pinned by digest.
145- - Maven Wrapper validates the Maven distribution with a SHA-256 checksum.
146- - Default branch governance is documented in ` docs/GOVERNANCE.md ` .
147- - ` .github/workflows/codeql.yml ` : static security analysis
148- - ` .github/workflows/scorecard.yml ` : OSSF scorecards check for supply-chain posture.
149- - ` .github/workflows/release.yml ` : verified tag releases with checksums, CycloneDX SBOM (JSON/XML), and GitHub artifact attestations.
150- - ` pom.xml ` : SpotBugs bytecode analysis and CycloneDX SBOM generation (JSON/XML) are wired into the Maven lifecycle.
151- - ` .github/ISSUE_TEMPLATE ` : bug report and feature request templates
152- - ` checkstyle ` config: ` src/main/resources/checkstyle/google_checks.xml `
153- - Dependency policy: ` CHANGELOG.md ` , ` CONTRIBUTING.md ` , ` SECURITY.md ` , ` CODE_OF_CONDUCT.md `
154- - Dependency baseline: ` docs/DEPENDENCY_POLICY.md `
155- - License: ` LICENSE ` (GNU GPL-3.0)
156- - ` docs/QUALITY.md ` : scoring-oriented quality evidence and workflow summary
157-
158- ### Documentation set
159-
160- - [ ` docs/ARCHITECTURE.md ` ] ( docs/ARCHITECTURE.md )
161- - [ ` docs/USAGE.md ` ] ( docs/USAGE.md )
162- - [ ` docs/TEST_PLAN.md ` ] ( docs/TEST_PLAN.md )
163- - [ ` docs/QUALITY.md ` ] ( docs/QUALITY.md )
164- - [ ` docs/GOVERNANCE.md ` ] ( docs/GOVERNANCE.md )
165- - [ ` docs/DEPENDENCY_POLICY.md ` ] ( docs/DEPENDENCY_POLICY.md )
166- - [ ` docs/SUPPLY_CHAIN.md ` ] ( docs/SUPPLY_CHAIN.md )
167-
168- ### What's not included
169-
170- - This is a compact portfolio project; it intentionally avoids heavy external frameworks and focuses on clean, testable Java core.
171- - No secrets are committed to source.
172-
173- ## Русский
174-
175- ### Что показывает репозиторий
17+ ## Что показывает репозиторий
17618
17719- Чёткие слои: ` config ` , ` audio ` , ` orchestration ` , ` storage ` , ` ui ` .
17820- Работа как через CLI, так и через Swing UI (` --ui ` ).
@@ -185,7 +27,7 @@ This enforces configured line/branch thresholds in `pom.xml`.
18527- Дополнительно: архитектурные проверки слоёв через ArchUnit.
18628- Проверяется корректная остановка фоновой записи и EDT-safe обновление Swing UI.
18729
188- ### Архитектура
30+ ## Архитектура
18931
19032``` mermaid
19133flowchart LR
@@ -205,7 +47,7 @@ flowchart LR
20547 UI --> Coordinator
20648```
20749
208- ### Запуск
50+ ## Запуск
20951
21052``` bash
21153git clone https://github.com/krotname/JavaSoundRecorder.git
@@ -215,7 +57,7 @@ cd JavaSoundRecorder
21557
21658В Windows используйте ` mvnw.cmd ` вместо ` ./mvnw ` .
21759
218- #### Запуск CLI
60+ ### Запуск CLI
21961
22062``` bash
22163./mvnw -q exec:java
@@ -227,15 +69,15 @@ cd JavaSoundRecorder
22769./mvnw -q exec:java -Dexec.mainClass=com.krotname.javasoundrecorder.Main -Dexec.args=" --ui"
22870```
22971
230- #### Запуск через Docker
72+ ### Запуск через Docker
23173
23274``` bash
23375./mvnw -q package
23476docker build -t javasoundrecorder .
23577docker run --rm javasoundrecorder
23678```
23779
238- ### Конфигурация
80+ ## Конфигурация
23981
24082| Переменная | Назначение |
24183| ---| ---|
@@ -247,7 +89,7 @@ docker run --rm javasoundrecorder
24789
24890Некорректные boolean-значения завершаются ошибкой. Папка Dropbox нормализуется к абсолютному пути Dropbox.
24991
250- ### Тестирование
92+ ## Тестирование
25193
25294``` bash
25395./mvnw -q -Dtest=* UnitTest test
@@ -263,7 +105,7 @@ docker run --rm javasoundrecorder
263105./mvnw -q verify
264106```
265107
266- ### Качество и документация
108+ ## Качество и документация
267109
268110- ` .github/workflows/ci.yml ` — запуск по категориям тестов и проверкам, включая architecture tests.
269111- ` .github/workflows/actionlint.yml ` — статическая проверка GitHub Actions workflow-файлов.
0 commit comments