node-mac-recorder 2.21.39 → 2.21.41

package/DUAL_RECORDING_PLAN.md

@@ -0,0 +1,243 @@
+# Dual/Multiple Window Recording Implementation Plan
+
+## Problem
+Current implementation uses **global state** in native code, allowing only ONE recording at a time.
+
+## Goal
+Support **multiple simultaneous recordings** - each with its own:
+- Window/Display target
+- Output file (temp_screen_0_xxx.mov, temp_screen_1_xxx.mov, etc.)
+- Independent start/stop control
+
+## Required Changes
+
+### 1. Native Code Refactoring (screen_capture_kit.mm)
+
+#### Current (Global State):
+```objc
+static SCStream *g_stream = nil;
+static BOOL g_isRecording = NO;
+static NSString *g_outputPath = nil;
+static AVAssetWriter *g_videoWriter = nil;
+```
+
+#### New (Session-Based State):
+```objc
+// Recording session structure
+@interface RecordingSession : NSObject
+@property (nonatomic, strong) NSString *sessionId;
+@property (nonatomic, strong) SCStream *stream;
+@property (nonatomic, strong) NSString *outputPath;
+@property (nonatomic, strong) AVAssetWriter *videoWriter;
+@property (nonatomic, strong) AVAssetWriterInput *videoInput;
+@property (nonatomic, strong) dispatch_queue_t videoQueue;
+@property (nonatomic, assign) BOOL isRecording;
+@property (nonatomic, assign) CMTime startTime;
+// ... other session-specific state
+@end
+
+// Global session registry
+static NSMutableDictionary<NSString *, RecordingSession *> *g_sessions = nil;
+static dispatch_queue_t g_sessionsQueue = nil;
+```
+
+#### Key Changes:
+
+1. **Session Management Functions**:
+   ```objc
+   + (NSString *)createRecordingSession;
+   + (RecordingSession *)getSession:(NSString *)sessionId;
+   + (void)removeSession:(NSString *)sessionId;
+   + (NSArray<NSString *> *)getActiveSessions;
+   ```
+
+2. **Modified API**:
+   ```objc
+   // Old: + (BOOL)startRecordingWithConfiguration:(NSDictionary *)config
+   // New:
+   + (NSString *)startRecordingWithConfiguration:(NSDictionary *)config
+                                        delegate:(id)delegate
+                                           error:(NSError **)error;
+   // Returns: sessionId (e.g., "rec_1762850131780")
+
+   // Old: + (void)stopRecording;
+   // New:
+   + (BOOL)stopRecording:(NSString *)sessionId;
+   ```
+
+3. **Stream Output Delegates**:
+   - Each session needs its own video/audio output delegates
+   - Delegates must know which session they belong to
+   - Frame callbacks route to correct writer
+
+### 2. JavaScript API Updates (index.js)
+
+#### Add Session Support:
+
+```javascript
+class MacRecorder extends EventEmitter {
+    constructor() {
+        super();
+        this.sessionId = null;  // Unique session ID from native
+        this.isRecording = false;
+        // ... existing code
+    }
+
+    async startRecording(outputPath, options = {}) {
+        // ... existing setup code ...
+
+        // Start native recording with session support
+        const recordingOptions = {
+            ...options,
+            // Request specific session management
+            createNewSession: true
+        };
+
+        // Native returns sessionId
+        const result = nativeBinding.startRecording(
+            outputPath,
+            recordingOptions
+        );
+
+        this.sessionId = result.sessionId;
+        this.isRecording = true;
+        // ...
+    }
+
+    async stopRecording() {
+        if (!this.sessionId) {
+            throw new Error("No active recording session");
+        }
+
+        // Stop specific session
+        const success = nativeBinding.stopRecording(this.sessionId);
+        // ...
+    }
+}
+```
+
+### 3. File Naming Strategy
+
+When multiple recordings are active:
+
+```javascript
+// First recording
+const timestamp = Date.now();
+const outputPath1 = `temp_screen_${timestamp}.mov`;
+
+// Second recording (same timestamp, different index)
+const outputPath2 = `temp_screen_1_${timestamp}.mov`;
+
+// Third recording
+const outputPath3 = `temp_screen_2_${timestamp}.mov`;
+```
+
+Or use session IDs:
+```javascript
+const outputPath = `temp_screen_${sessionId}.mov`;
+```
+
+## Implementation Steps
+
+### Phase 1: Core Session Infrastructure ✅
+- [ ] Create RecordingSession class
+- [ ] Add session registry (Map/Dictionary)
+- [ ] Implement session lifecycle methods
+- [ ] Add thread-safe session access
+
+### Phase 2: Refactor Native Recording ⏳
+- [ ] Update startRecording to return sessionId
+- [ ] Modify video output delegates to use session
+- [ ] Modify audio output delegates to use session
+- [ ] Update stopRecording to accept sessionId
+- [ ] Test single session (backward compatibility)
+
+### Phase 3: Multi-Session Support 🔜
+- [ ] Test two simultaneous recordings
+- [ ] Test different targets (window vs display)
+- [ ] Add session limits (max 4 simultaneous?)
+- [ ] Handle memory/performance implications
+
+### Phase 4: JavaScript API 🔜
+- [ ] Update MacRecorder to use sessions
+- [ ] Add getActiveSessions() method
+- [ ] Add getAllRecordingStatuses() method
+- [ ] Update documentation
+
+### Phase 5: Testing 🧪
+- [ ] Test dual window recording
+- [ ] Test dual display recording
+- [ ] Test mixed (window + display)
+- [ ] Performance benchmarks
+- [ ] Memory usage tests
+
+## Technical Considerations
+
+### Memory & Performance
+- Each SCStream captures frames independently
+- 2 recordings @ 1080p 60fps = ~240MB/s uncompressed
+- Limit simultaneous recordings (recommend max 4)
+- Add memory warnings
+
+### Thread Safety
+- Use dispatch_queue for session access
+- Prevent race conditions on session creation/removal
+- Careful with delegate callbacks
+
+### File Naming
+- Option A: Use indices (temp_screen_0_xxx, temp_screen_1_xxx)
+- Option B: Use session IDs (temp_screen_rec_xxx)
+- Option C: Let user specify base name
+
+### Backward Compatibility
+- Single recording should work as before
+- Default behavior: create implicit session
+- Advanced users: explicit session management
+
+## Example Usage
+
+```javascript
+const MacRecorder = require('node-mac-recorder');
+
+async function recordTwoWindows() {
+    const recorder1 = new MacRecorder();
+    const recorder2 = new MacRecorder();
+
+    const windows = await recorder1.getWindows();
+
+    // Start both recordings
+    await recorder1.startRecording('output/window1.mov', {
+        windowId: windows[0].id
+    });
+
+    await recorder2.startRecording('output/window2.mov', {
+        windowId: windows[1].id
+    });
+
+    // Record for 10 seconds
+    await new Promise(r => setTimeout(r, 10000));
+
+    // Stop both
+    await recorder1.stopRecording();
+    await recorder2.stopRecording();
+
+    console.log('Both recordings complete!');
+}
+```
+
+## Timeline Estimate
+
+- **Phase 1-2**: 4-6 hours (core infrastructure)
+- **Phase 3**: 2-3 hours (multi-session testing)
+- **Phase 4**: 1-2 hours (JS API updates)
+- **Phase 5**: 2-3 hours (comprehensive testing)
+
+**Total: ~10-14 hours** for complete implementation
+
+## Questions to Decide
+
+1. **Session Limit**: Max how many simultaneous recordings? (Recommend 2-4)
+2. **File Naming**: Automatic indices or user-specified?
+3. **API Style**: Explicit sessions or implicit (current MacRecorder instances)?
+4. **Performance**: Add automatic quality reduction for multiple streams?
+5. **Error Handling**: What if one session fails? Stop all or continue others?

package/MULTI_RECORDING.md

@@ -0,0 +1,270 @@
+# Multi-Window/Display Recording
+
+## 🎉 Özellik: Aynı Anda Birden Fazla Kayıt
+
+node-mac-recorder artık **aynı anda birden fazla pencere veya ekranı** kaydetme yeteneğine sahip!
+
+### ✨ Nasıl Çalışıyor?
+
+**Child Process Yaklaşımı**: Her `MacRecorder` instance'ı kendi ayrı Node.js process'inde çalışır. Bu sayede:
+
+- ✅ Native kod değişikliği **GEREKMEDİ**
+- ✅ Her process kendi **bağımsız state**'ine sahip
+- ✅ Gerçek **paralel kayıt** (aynı anda)
+- ✅ Kolay kullanım - sadece yeni bir class kullan!
+
+## 📖 Kullanım
+
+### Basit Örnek - İki Display Kaydı
+
+```javascript
+const MacRecorder = require('./index-multiprocess');
+
+async function recordTwoDisplays() {
+    // Her recorder kendi process'inde çalışır
+    const recorder1 = new MacRecorder();
+    const recorder2 = new MacRecorder();
+
+    // Display'leri al
+    const displays = await recorder1.getDisplays();
+
+    // İki kaydı başlat (sırayla - ScreenCaptureKit init için)
+    await recorder1.startRecording('output/display1.mov', {
+        displayId: displays[0].id,
+        frameRate: 30
+    });
+
+    await new Promise(r => setTimeout(r, 1000)); // Kısa bekleme
+
+    await recorder2.startRecording('output/display2.mov', {
+        displayId: displays[1]?.id || displays[0].id,
+        frameRate: 30
+    });
+
+    // İkisi de aynı anda kaydediyor!
+    console.log('📹 İki display aynı anda kaydediliyor...');
+
+    // 10 saniye kaydet
+    await new Promise(r => setTimeout(r, 10000));
+
+    // İkisini de durdur
+    await recorder1.stopRecording();
+    await recorder2.stopRecording();
+
+    // Cleanup
+    recorder1.destroy();
+    recorder2.destroy();
+
+    console.log('✅ Kayıtlar tamamlandı!');
+}
+
+recordTwoDisplays();
+```
+
+### İleri Seviye - Farklı Window'ları Kaydet
+
+```javascript
+const MacRecorder = require('./index-multiprocess');
+
+async function recordTwoWindows() {
+    const recorder1 = new MacRecorder();
+    const recorder2 = new MacRecorder();
+
+    // Açık pencereleri al
+    const windows = await recorder1.getWindows();
+
+    if (windows.length < 2) {
+        console.error('En az 2 pencere açık olmalı!');
+        return;
+    }
+
+    console.log(`Kaydedilecek pencereler:`);
+    console.log(`1. ${windows[0].appName} - ${windows[0].title}`);
+    console.log(`2. ${windows[1].appName} - ${windows[1].title}`);
+
+    // Event listeners
+    recorder1.on('recordingStarted', () => {
+        console.log('✅ Pencere 1 kaydı başladı');
+    });
+
+    recorder2.on('recordingStarted', () => {
+        console.log('✅ Pencere 2 kaydı başladı');
+    });
+
+    // İlk pencereyi kaydet
+    await recorder1.startRecording('output/window1.mov', {
+        windowId: windows[0].id,
+        captureCursor: true,
+        frameRate: 30
+    });
+
+    // 1 saniye bekle (ScreenCaptureKit init için)
+    await new Promise(r => setTimeout(r, 1000));
+
+    // İkinci pencereyi kaydet
+    await recorder2.startRecording('output/window2.mov', {
+        windowId: windows[1].id,
+        captureCursor: true,
+        frameRate: 30
+    });
+
+    // Her ikisi de paralel kaydediyor!
+    await new Promise(r => setTimeout(r, 10000));
+
+    // Durdur
+    await recorder1.stopRecording();
+    await recorder2.stopRecording();
+
+    // Cleanup
+    recorder1.destroy();
+    recorder2.destroy();
+}
+
+recordTwoWindows();
+```
+
+## 📝 Önemli Notlar
+
+### Zamanlama (Timing)
+
+ScreenCaptureKit'in düzgün başlaması için **kayıtlar arasında ~1 saniye** bekleme gerekli:
+
+```javascript
+await recorder1.startRecording(...);
+await new Promise(r => setTimeout(r, 1000));  // ⚠️ ÖNEMLİ!
+await recorder2.startRecording(...);
+```
+
+### Dosya Adlandırma
+
+Her kayıt **farklı bir dosyaya** yazılmalı:
+
+```javascript
+✅ DOĞRU:
+recorder1.startRecording('video1.mov');
+recorder2.startRecording('video2.mov');
+
+❌ YANLIŞ:
+recorder1.startRecording('video.mov');
+recorder2.startRecording('video.mov');  // Aynı dosya!
+```
+
+### Performans
+
+- **2 kayıt**: Sorunsuz çalışır
+- **3-4 kayıt**: İyi çalışır, ancak CPU kullanımı artar
+- **5+ kayıt**: Önerilmez - sistem yavaşlayabilir
+
+### Cleanup
+
+Recording bittiğinde mutlaka `destroy()` çağırın:
+
+```javascript
+recorder.destroy();  // Worker process'i temizler
+```
+
+## 🧪 Test
+
+```bash
+# Multi-process test
+node test-multiprocess.js
+
+# İki display aynı anda
+node test-dual-recording.js
+
+# İki window aynı anda (en az 2 pencere açık olmalı)
+node test-dual-window.js
+```
+
+## 🔧 Teknik Detaylar
+
+### Mimari
+
+```
+Ana Process (Node.js)
+├── MacRecorderMultiProcess Instance 1
+│   └── Worker Process 1 (ayrı Node.js process)
+│       └── Native Binding (ScreenCaptureKit)
+│           └── Video File 1
+│
+└── MacRecorderMultiProcess Instance 2
+    └── Worker Process 2 (ayrı Node.js process)
+        └── Native Binding (ScreenCaptureKit)
+            └── Video File 2
+```
+
+### IPC (Inter-Process Communication)
+
+Worker process'ler ile iletişim:
+
+```javascript
+// Ana process → Worker
+worker.send({ type: 'startRecording', data: { ... } });
+
+// Worker → Ana process
+process.send({ type: 'event', event: 'recordingStarted', data: { ... } });
+```
+
+### Global State Sorunu - ÇÖZÜLDÜ! ✅
+
+**Eski sorun**: Native kod global state kullanıyordu → Sadece 1 kayıt
+
+**Çözüm**: Her worker ayrı process → Her biri kendi global state'i
+
+```
+Process 1: g_isRecording = true  (Video 1 kaydediyor)
+Process 2: g_isRecording = true  (Video 2 kaydediyor)
+           ↑ Ayrı memory space, conflict yok!
+```
+
+## ⚡ Performans İpuçları
+
+1. **Frame Rate**: Çoklu kayıt için 30 FPS yeterli (60 yerine)
+2. **Başlangıç Gecikmesi**: Her recorder arasında 1 saniye
+3. **Cleanup**: Kayıt bitince mutlaka `destroy()` çağır
+4. **Memory**: Her worker ~200MB kullanır
+
+## 🐛 Sorun Giderme
+
+### "Worker not ready" hatası
+```javascript
+// Çözüm: Worker'ın hazır olmasını bekle
+await new Promise(r => setTimeout(r, 500));
+```
+
+### Sadece bir dosya oluştu
+```javascript
+// Çözüm: Kayıtlar arasında bekleme ekle
+await recorder1.startRecording(...);
+await new Promise(r => setTimeout(r, 1000));  // Ekle!
+await recorder2.startRecording(...);
+```
+
+### Worker crash oluyor
+```javascript
+// Çözüm: Event listener ekle
+recorder.on('error', (err) => {
+    console.error('Worker error:', err);
+});
+```
+
+## 📊 Karşılaştırma
+
+| Özellik | Tek Process (index.js) | Multi-Process (index-multiprocess.js) |
+|---------|------------------------|---------------------------------------|
+| Aynı anda kayıt | ❌ Hayır | ✅ Evet |
+| Native kod değişikliği | - | ❌ Gerek yok |
+| Memory kullanımı | Düşük | Orta (worker başına ~200MB) |
+| Kullanım kolaylığı | Kolay | Çok kolay |
+| Performans | En iyi | İyi |
+
+## 🎯 Kullanım Senaryoları
+
+1. **Çoklu Monitor Kaydı**: Her monitörü ayrı dosyaya
+2. **Uygulama + Notlar**: Bir ekranda uygulama, diğerde notlar
+3. **Webinar + Kamera**: Ekran + webcam ayrı ayrı
+4. **Oyun + Chat**: Oyun penceresi + Discord ayrı
+
+## 📄 Lisans
+
+Bu özellik node-mac-recorder'ın bir parçasıdır ve aynı lisans altındadır.