Skip to content

Commit 7b4ee0a

Browse files
Diyoncrz18Diyoncrz18
committed
docs: prepare project for open source contributors
1 parent ab864e5 commit 7b4ee0a

9 files changed

Lines changed: 312 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: Bug report
3+
about: Report a reproducible problem
4+
title: "[Bug]: "
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
## What happened?
10+
11+
Describe the bug clearly.
12+
13+
## Steps to reproduce
14+
15+
1.
16+
2.
17+
3.
18+
19+
## Expected behavior
20+
21+
What should have happened?
22+
23+
## Actual behavior
24+
25+
What happened instead?
26+
27+
## Environment
28+
29+
- OS:
30+
- Python version:
31+
- Run mode: local or `--api`
32+
- Provider/model, if using API mode:
33+
34+
## Logs
35+
36+
Paste relevant logs here. Remove API keys, private transcripts, and personal information.
37+
38+
```text
39+
40+
```
41+
42+
## Additional context
43+
44+
Add screenshots or notes if helpful.

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Contribution guide
4+
url: https://github.com/Diyoncrz18/realtime-dual-transcriber/blob/main/CONTRIBUTING.md
5+
about: Read setup, testing, and pull request guidance before contributing.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: Feature request
3+
about: Suggest an improvement or new capability
4+
title: "[Feature]: "
5+
labels: enhancement
6+
assignees: ""
7+
---
8+
9+
## Problem
10+
11+
What problem would this feature solve?
12+
13+
## Proposed solution
14+
15+
Describe the behavior you want.
16+
17+
## Alternatives considered
18+
19+
Mention other approaches if any.
20+
21+
## Impact
22+
23+
Who would benefit from this feature?
24+
25+
## Additional context
26+
27+
Add mockups, examples, or related links if useful.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
## Summary
2+
3+
Describe what this pull request changes and why.
4+
5+
## Type of Change
6+
7+
- [ ] Bug fix
8+
- [ ] Feature
9+
- [ ] Documentation
10+
- [ ] Test
11+
- [ ] Refactor
12+
13+
## Testing
14+
15+
Commands run:
16+
17+
```powershell
18+
19+
```
20+
21+
## Realtime Audio Checklist
22+
23+
- [ ] Microphone transcription still works.
24+
- [ ] Speaker/system audio transcription still works.
25+
- [ ] UI does not freeze during transcription or translation.
26+
- [ ] Translation remains manual through `Selesai` unless this PR intentionally changes it.
27+
28+
## Security Checklist
29+
30+
- [ ] No API keys, `.env`, `keys.py`, logs, recordings, or private transcripts are included.
31+
- [ ] Error logs do not print API keys.
32+
33+
## Screenshots or Notes
34+
35+
Add screenshots, logs without secrets, or context that helps reviewers.

‎CODE_OF_CONDUCT.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Code of Conduct
2+
3+
This project welcomes contributors of all skill levels. Please keep the community practical, respectful, and helpful.
4+
5+
## Expected Behavior
6+
7+
- Be respectful when discussing bugs, design choices, and tradeoffs.
8+
- Assume good intent, especially with new contributors.
9+
- Give feedback that is specific and actionable.
10+
- Keep issues and pull requests focused on the project.
11+
- Respect privacy. Do not share other people's API keys, recordings, transcripts, screenshots, or personal information.
12+
13+
## Unacceptable Behavior
14+
15+
- Harassment, threats, insults, or discriminatory comments.
16+
- Publishing private information without permission.
17+
- Spamming issues, pull requests, or discussions.
18+
- Intentionally submitting malicious code or code that leaks secrets.
19+
20+
## Reporting
21+
22+
If you see behavior that makes the project unsafe or unwelcoming, open an issue with the label `community` or contact the maintainer through the repository owner profile. Reports will be reviewed with care and handled according to the severity of the situation.
23+
24+
## Enforcement
25+
26+
Maintainers may remove comments, close issues, reject pull requests, or block accounts when behavior harms the project or its contributors.

‎CONTRIBUTING.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Contributing
2+
3+
Thanks for wanting to improve realtime-dual-transcriber. This project is open to forks, pull requests, bug reports, experiments, and documentation improvements.
4+
5+
## Ways to Contribute
6+
7+
- Fix bugs in microphone, speaker, transcription, translation, or UI behavior.
8+
- Improve realtime performance and transcription accuracy.
9+
- Add tests for transcript state, API configuration, and UI-safe behavior.
10+
- Improve setup documentation for Windows users.
11+
- Suggest better defaults for Groq, OpenAI-compatible providers, or local Whisper mode.
12+
13+
## Before You Start
14+
15+
1. Fork the repository.
16+
2. Create a feature branch from `main`.
17+
3. Keep changes focused and easy to review.
18+
4. Never commit `.env`, `keys.py`, API keys, logs, recordings, model files, or personal data.
19+
20+
```powershell
21+
git clone https://github.com/YOUR_USERNAME/realtime-dual-transcriber.git
22+
cd realtime-dual-transcriber
23+
git checkout -b feature/your-change
24+
```
25+
26+
## Local Setup
27+
28+
```powershell
29+
python -m venv .venv
30+
.\.venv\Scripts\Activate.ps1
31+
python -m pip install --upgrade pip
32+
pip install -r requirements.txt
33+
Copy-Item .env.example .env
34+
```
35+
36+
Fill `.env` with your own provider key if you want to test API mode. Keep it private.
37+
38+
## Running
39+
40+
Local mode:
41+
42+
```powershell
43+
.\.venv\Scripts\python.exe main.py
44+
```
45+
46+
API mode:
47+
48+
```powershell
49+
.\.venv\Scripts\python.exe main.py --api
50+
```
51+
52+
## Tests
53+
54+
Run these before opening a pull request:
55+
56+
```powershell
57+
.\.venv\Scripts\python.exe -m unittest discover -s tests
58+
.\.venv\Scripts\python.exe -m py_compile main.py AudioRecorder.py AudioTranscriber.py TranscriberModels.py
59+
```
60+
61+
## Pull Request Checklist
62+
63+
- The change is scoped to one clear problem or feature.
64+
- Tests were added or updated when behavior changed.
65+
- Existing microphone and speaker transcription still work.
66+
- Translation remains manual through the `Selesai` button unless the PR explicitly discusses changing that flow.
67+
- No secrets, recordings, generated model files, or local machine paths were committed.
68+
- The README or examples were updated if configuration changed.
69+
70+
## Good First Issues
71+
72+
Good first contributions include:
73+
74+
- Better setup notes for FFmpeg and Windows audio devices.
75+
- Small UI polish that does not rewrite the app.
76+
- More unit tests for transcript merging and translation state.
77+
- Safer defaults for noisy rooms or low-volume speaker audio.
78+
79+
## Review Style
80+
81+
Reviews focus on correctness, realtime behavior, security, privacy, and keeping the app easy to run. Clear screenshots, terminal logs without secrets, and short reproduction steps make a PR much easier to merge.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Diyoncrz18
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# realtime-dual-transcriber
22

3+
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
4+
[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-blue.svg)](CONTRIBUTING.md)
5+
[![Forks welcome](https://img.shields.io/badge/forks-welcome-brightgreen.svg)](CONTRIBUTING.md)
6+
37
realtime-dual-transcriber is a Windows desktop application for live transcription from two audio sources at the same time:
48

59
- microphone input, shown as `You`
@@ -19,6 +23,34 @@ The application displays a real-time transcript in a desktop UI and can optional
1923
- Secret-safe local configuration through `.env` or `keys.py`
2024
- Built-in unit tests for transcript state and API authentication handling
2125

26+
## Open Source and Contributions
27+
28+
This project is open source under the MIT License and welcomes forks, pull requests, bug reports, and documentation improvements.
29+
30+
Start contributing:
31+
32+
1. Fork this repository.
33+
2. Create a branch from `main`.
34+
3. Make a focused change.
35+
4. Run the tests.
36+
5. Open a pull request.
37+
38+
```powershell
39+
git clone https://github.com/YOUR_USERNAME/realtime-dual-transcriber.git
40+
cd realtime-dual-transcriber
41+
git checkout -b feature/your-change
42+
```
43+
44+
Helpful links:
45+
46+
- [Contribution guide](CONTRIBUTING.md)
47+
- [Code of conduct](CODE_OF_CONDUCT.md)
48+
- [Security policy](SECURITY.md)
49+
- [Bug report template](.github/ISSUE_TEMPLATE/bug_report.md)
50+
- [Feature request template](.github/ISSUE_TEMPLATE/feature_request.md)
51+
52+
Good first contributions include Windows setup improvements, UI polish, transcript-state tests, provider configuration examples, and safer defaults for noisy audio environments.
53+
2254
## Repository
2355

2456
```powershell
@@ -243,7 +275,11 @@ stateDiagram-v2
243275
|-- main.py # Desktop UI entry point
244276
|-- custom_speech_recognition/ # Speech recognition compatibility layer
245277
|-- tests/ # Unit tests
278+
|-- .github/ # GitHub Actions and contribution templates
246279
|-- .env.example # Environment variable template
280+
|-- CONTRIBUTING.md # Contributor onboarding guide
281+
|-- CODE_OF_CONDUCT.md # Community behavior expectations
282+
|-- LICENSE # MIT License
247283
|-- keys.example.py # Python credential template
248284
|-- requirements.txt # Python dependencies
249285
`-- README.md # Project documentation
@@ -291,6 +327,14 @@ Translation runs when you click the `Selesai` button. While speaking, the active
291327
- The repository includes a GitHub Actions secret scan for common API key patterns.
292328
- If a real API key was ever committed, revoke it immediately and create a new one.
293329

330+
## Project Ownership
331+
332+
realtime-dual-transcriber is an independent open-source project developed and maintained by `Diyoncrz18`.
333+
334+
## License
335+
336+
This project is licensed under the [MIT License](LICENSE).
337+
294338
## Maintainer
295339

296340
Maintained by `Diyoncrz18`.

‎SECURITY.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
Security fixes are handled on the `main` branch.
6+
7+
## Reporting a Vulnerability
8+
9+
Please do not publicly post API keys, transcripts, audio recordings, or exploit details in an issue.
10+
11+
If you find a security problem:
12+
13+
1. Open a minimal issue that says a security report is available, without secrets or exploit details.
14+
2. Contact the repository owner through GitHub profile information.
15+
3. Include reproduction steps, affected files, and impact when sharing details privately.
16+
17+
## Sensitive Data
18+
19+
This project can process microphone audio, speaker audio, transcripts, and API credentials. Contributors should avoid committing:
20+
21+
- `.env`
22+
- `keys.py`
23+
- API keys
24+
- audio recordings
25+
- transcript logs
26+
- generated model files
27+
- screenshots that reveal private conversations
28+
29+
The repository includes secret-scan automation, but contributors are still responsible for checking their changes before opening a pull request.

0 commit comments

Comments
 (0)