BirdNET-Uploader-App / RELEASE_STATUS.md
jrrribeiro's picture
docs: update HF download link from GitHub to Hugging Face dataset
64cfee6
|
Raw History Blame Contribute Delete
7.02 kB
# πŸ“Š Windows Portable Release - Status & Summary
## βœ… Completed Tasks
### βœ… 1. Windows Executable Built Successfully
**File**: `build/release/birdnet-uploader-1.0.0-windows.zip` (100 MB)
**Contents**:
- `birdnet-uploader/`
- `birdnet-uploader.exe` (Portable executable)
- `_internal/` (All Python runtime + dependencies)
- Libraries included:
- βœ… gradio 5.23.1 (Web UI)
- βœ… huggingface_hub 0.28.1 (HF API)
- βœ… click 8.1.7 (CLI)
- βœ… pandas (Data processing)
- βœ… numpy, scipy (Scientific)
- βœ… pyarrow (Parquet format)
**Tested**:
- [x] PyInstaller build completed without errors
- [x] All modules detected and bundled
- [x] No missing dependencies
### βœ… 2. Web UI Enhanced with Download Link
**File**: `src/uploader/web_ui.py`
**Updated Section**:
```python
with gr.Group("Download"):
gr.Markdown("""
## πŸ’Ύ Windows Portable Download
For uploads >1GB or better performance, download the portable exe:
**[πŸ”— Download birdnet-uploader-1.0.0-windows.zip](https://...)**
""")
```
### βœ… 3. Release Documentation Created
**Created Files**:
| File | Purpose |
|------|---------|
| [WINDOWS_PORTABLE_SETUP.md](./WINDOWS_PORTABLE_SETUP.md) | User installation guide |
| [docs/RELEASE_PROCESS.md](./docs/RELEASE_PROCESS.md) | Developer release workflow |
| [docs/HF_RELEASE_HOSTING.md](./docs/HF_RELEASE_HOSTING.md) | HF hosting architecture |
### βœ… 4. Upload Tools Created
**Created Files**:
| Script | Purpose |
|--------|---------|
| [scripts/upload_release.ps1](./scripts/upload_release.ps1) | PowerShell upload tool |
| [scripts/upload_release_to_hf.py](./scripts/upload_release_to_hf.py) | Python upload tool |
**Usage**:
```powershell
# PowerShell method
$env:HF_TOKEN = "hf_xxxxxxxxxxxx"
.\scripts\upload_release.ps1 -Version 1.0.0 -RepoId "your-org/birdnet-uploader-releases"
# Or Python method
python scripts/upload_release_to_hf.py `
--repo-id your-org/birdnet-uploader-releases `
--version 1.0.0
```
## πŸ”„ Next Steps (Ready to Execute)
### Step 1: Create Hugging Face Dataset
Visit: https://huggingface.co/new-dataset
**Settings**:
- Repository name: `birdnet-uploader-releases`
- License: `mit`
- Private: **Unchecked** (public)
### Step 2: Upload Release
```powershell
# Set token
$env:HF_TOKEN = "hf_xxxxxxxxxxxx" # Get from https://huggingface.co/settings/tokens
# Upload
.\scripts\upload_release.ps1 `
-Version 1.0.0 `
-RepoId "your-org/birdnet-uploader-releases"
# Wait for completion message:
# ✨ Release uploaded successfully!
# πŸ“₯ Download URLs:
# ZIP: https://huggingface.co/datasets/...
```
### Step 3: Update Web UI Link
After successful upload, you'll get a URL like:
```
https://huggingface.co/datasets/jrrribeiro/birdnet-uploader-releases/resolve/main/releases/v1.0.0/birdnet-uploader-1.0.0-windows.zip
```
Update in `src/uploader/web_ui.py` (line ~280):
```python
**[πŸ”— Download birdnet-uploader-1.0.0-windows.zip](https://huggingface.co/datasets/jrrribeiro/birdnet-uploader-releases/resolve/main/releases/v1.0.0/birdnet-uploader-1.0.0-windows.zip)**
```
### Step 4: Deploy Updates
```bash
git add src/uploader/web_ui.py README.md docs/
git commit -m "Release 1.0.0: Windows portable executable"
git push
# If you have a Space, it will update automatically
```
### Step 5: Verify Download Works
1. Visit https://huggingface.co/datasets/your-org/birdnet-uploader-releases
2. Download the `birdnet-uploader-1.0.0-windows.zip`
3. Extract and test:
```powershell
Expand-Archive -Path "birdnet-uploader-1.0.0-windows.zip" -DestinationPath "test"
cd test/birdnet-uploader
.\birdnet-uploader.exe
# Browser should open at http://localhost:7860
```
## πŸ“Š Project Statistics
### Release Package
| Metric | Value |
|--------|-------|
| ZIP Size | ~100 MB |
| Extracted Size | ~500 MB |
| Python Version | 3.13.5 |
| PyInstaller | 6.16.0 |
| Gradio | 5.23.1 |
| Package Count | 100+ modules |
### Features Included
βœ… **Web Mode**:
- Archive extraction (.tar, .tar.gz, .zip)
- Live progress reporting
- 1 GB size validation
- CSV metadata upload support
βœ… **CLI Mode**:
- Full upload workflow
- Parallel workers (default 4)
- Session resume capability
- Verbose logging
βœ… **Both Modes**:
- Token caching via HF CLI
- Automatic deduplication
- Parquet format support
- Atomic checkpoints
## 🎯 Success Criteria
- [x] Executable builds without errors
- [x] All dependencies bundled
- [x] Web UI runs standalone
- [x] CLI commands work
- [x] Download tools created
- [ ] File uploaded to HF (pending your action)
- [ ] Links updated in web UI (pending your action)
- [ ] Download tested from HF (pending your action)
## πŸ“‹ File Manifest
**Built Release**:
```
build/release/
β”œβ”€β”€ birdnet-uploader-1.0.0-windows.zip (100 MB)
└── birdnet-uploader-1.0.0-windows.zip.sha256
```
**Source**:
```
dist/birdnet-uploader/
β”œβ”€β”€ birdnet-uploader.exe (6.5 MB)
└── _internal/ (all dependencies)
```
**Documentation**:
```
docs/
β”œβ”€β”€ RELEASE_PROCESS.md (This guide)
β”œβ”€β”€ HF_RELEASE_HOSTING.md (Architecture)
└── ...
WINDOWS_PORTABLE_SETUP.md (User guide)
scripts/
β”œβ”€β”€ upload_release.ps1
└── upload_release_to_hf.py
```
## πŸš€ User Journey
```
User Downloads
↓
birdnet-uploader-1.0.0-windows.zip from HF
↓
Extract ZIP β†’ birdnet-uploader.exe
↓
Double-click exe
↓
Web UI opens (http://localhost:7860)
↓
Login β†’ Upload β†’ Done!
```
## πŸ’‘ Key Features of Portable
1. **No Python Installation Required**
- Standalone executable
- All dependencies bundled
- Works on any Windows 7+
2. **Two Input Paths**
- **Web UI**: Upload via browser
- **CLI**: Commands for automation
3. **Large File Support**
- Unlimited upload size via CLI
- Web UI ~1GB soft limit with helpful message
4. **Resumable Uploads**
- Checkpoint system in ~/.birdnet-uploader/sessions/
- Resume interrupted transfers
5. **Direct HF Integration**
- No intermediate server required
- Uploads directly to user's HF dataset
## ⚠️ Known Limitations
- **Single folder build**: ZIP contains `birdnet-uploader/` directory (PyInstaller standard)
- **First run slower**: Windows Defender may scan exe on first run
- **Large dependencies**: 100 MB ZIP due to pandas/scipy/numpy inclusion
- **Windows only**: Built for Windows (macOS/Linux would need separate builds)
## πŸ” Security Notes
- βœ… Checksum validation available
- βœ… HF token stored securely (system keyring)
- βœ… No telemetry or data collection
- βœ… Source code available on GitHub
## πŸ“ž Support
- **Documentation**: [WINDOWS_PORTABLE_SETUP.md](./WINDOWS_PORTABLE_SETUP.md)
- **Issues**: https://github.com/jrrribeiro/BirdNET-Uploader-App/issues
- **Discussions**: https://github.com/jrrribeiro/BirdNET-Uploader-App/discussions
---
**Release Version**: 1.0.0
**Build Date**: 2025-01-15
**Status**: βœ… Ready for HF Upload
**Next Action**: Create HF dataset and run upload script