node-mac-recorder 1.0.5 → 1.2.0

package/README.md

@@ -11,6 +11,7 @@ A powerful native macOS screen recording Node.js package with advanced window se
 - 🎯 **Area Selection** - Record custom screen regions
 - 🖱️ **Multi-Display Support** - Automatic display detection and selection
 - 🎨 **Cursor Control** - Toggle cursor visibility in recordings
+- 🖱️ **Cursor Tracking** - Track mouse position, cursor types, and click events
 
 🎵 **Granular Audio Controls**
 
@@ -25,6 +26,7 @@ A powerful native macOS screen recording Node.js package with advanced window se
 - 🎯 **Automatic Coordinate Conversion** - Handle multi-display coordinate systems
 - 📐 **Display ID Detection** - Automatically select correct display for window recording
 - 🖼️ **Window Filtering** - Smart filtering of recordable windows
+- 👁️ **Preview Thumbnails** - Generate window and display preview images
 
 ⚙️ **Customization Options**
 
@@ -202,6 +204,92 @@ console.log(status);
 // }
 ```
 
+#### `getWindowThumbnail(windowId, options?)`
+
+Captures a thumbnail preview of a specific window.
+
+```javascript
+const thumbnail = await recorder.getWindowThumbnail(12345, {
+	maxWidth: 400, // Maximum width (default: 300)
+	maxHeight: 300, // Maximum height (default: 200)
+});
+
+// Returns: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
+// Can be used directly in <img> tags or saved as file
+```
+
+#### `getDisplayThumbnail(displayId, options?)`
+
+Captures a thumbnail preview of a specific display.
+
+```javascript
+const thumbnail = await recorder.getDisplayThumbnail(0, {
+	maxWidth: 400, // Maximum width (default: 300)
+	maxHeight: 300, // Maximum height (default: 200)
+});
+
+// Returns: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
+// Perfect for display selection UI
+```
+
+### Cursor Tracking Methods
+
+#### `startCursorTracking(outputPath)`
+
+Starts tracking cursor movements and saves data to JSON file.
+
+```javascript
+await recorder.startCursorTracking("./cursor-data.json");
+// Cursor tracking started - will record position, cursor type, and events
+```
+
+#### `stopCursorTracking()`
+
+Stops cursor tracking and saves collected data.
+
+```javascript
+await recorder.stopCursorTracking();
+// Data saved to specified JSON file
+```
+
+#### `getCursorPosition()`
+
+Gets current cursor position and type.
+
+```javascript
+const position = recorder.getCursorPosition();
+console.log(position);
+// {
+//   x: 1234,
+//   y: 567,
+//   cursorType: "default" // "default", "pointer", "grabbing", "text"
+// }
+```
+
+#### `getCursorTrackingStatus()`
+
+Returns cursor tracking status and data count.
+
+```javascript
+const status = recorder.getCursorTrackingStatus();
+console.log(status);
+// {
+//   isTracking: true,
+//   dataCount: 1250,
+//   hasEventTap: true,
+//   hasRunLoopSource: true
+// }
+```
+
+#### `saveCursorData(outputPath)`
+
+Manually saves current cursor data to file.
+
+```javascript
+await recorder.saveCursorData("./cursor-backup.json");
+// Data saved to file
+```
+
 ## Usage Examples
 
 ### Window-Specific Recording
@@ -311,6 +399,163 @@ recorder.on("completed", (outputPath) => {
 await recorder.startRecording("./event-recording.mov");
 ```
 
+### Window Selection with Thumbnails
+
+```javascript
+const recorder = new MacRecorder();
+
+// Get windows with thumbnail previews
+const windows = await recorder.getWindows();
+
+console.log("Available windows with previews:");
+for (const window of windows) {
+	console.log(`${window.appName} - ${window.name}`);
+
+	try {
+		// Generate thumbnail for each window
+		const thumbnail = await recorder.getWindowThumbnail(window.id, {
+			maxWidth: 200,
+			maxHeight: 150,
+		});
+
+		console.log(`Thumbnail: ${thumbnail.substring(0, 50)}...`);
+
+		// Use thumbnail in your UI:
+		// <img src="${thumbnail}" alt="Window Preview" />
+	} catch (error) {
+		console.log(`No preview available: ${error.message}`);
+	}
+}
+```
+
+### Display Selection Interface
+
+```javascript
+const recorder = new MacRecorder();
+
+async function createDisplaySelector() {
+	const displays = await recorder.getDisplays();
+
+	const displayOptions = await Promise.all(
+		displays.map(async (display, index) => {
+			try {
+				const thumbnail = await recorder.getDisplayThumbnail(display.id);
+				return {
+					id: display.id,
+					name: `Display ${index + 1}`,
+					resolution: display.resolution,
+					thumbnail: thumbnail,
+					isPrimary: display.isPrimary,
+				};
+			} catch (error) {
+				return {
+					id: display.id,
+					name: `Display ${index + 1}`,
+					resolution: display.resolution,
+					thumbnail: null,
+					isPrimary: display.isPrimary,
+				};
+			}
+		})
+	);
+
+	return displayOptions;
+}
+```
+
+### Cursor Tracking Usage
+
+```javascript
+const recorder = new MacRecorder();
+
+async function trackUserInteraction() {
+	// Start cursor tracking
+	await recorder.startCursorTracking("./user-interactions.json");
+	console.log("Cursor tracking started...");
+
+	// Monitor real-time cursor position
+	const monitorInterval = setInterval(() => {
+		const position = recorder.getCursorPosition();
+		console.log(
+			`Cursor: ${position.x}, ${position.y} (${position.cursorType})`
+		);
+
+		const status = recorder.getCursorTrackingStatus();
+		console.log(`Tracking status: ${status.dataCount} positions recorded`);
+	}, 100); // Check every 100ms
+
+	// Track for 10 seconds
+	setTimeout(async () => {
+		clearInterval(monitorInterval);
+
+		// Stop tracking and save data
+		await recorder.stopCursorTracking();
+		console.log("Cursor tracking completed!");
+
+		// Load and analyze the data
+		const fs = require("fs");
+		const data = JSON.parse(
+			fs.readFileSync("./user-interactions.json", "utf8")
+		);
+
+		console.log(`Total interactions recorded: ${data.length}`);
+
+		// Analyze cursor types
+		const cursorTypes = {};
+		data.forEach((item) => {
+			cursorTypes[item.cursorType] = (cursorTypes[item.cursorType] || 0) + 1;
+		});
+
+		console.log("Cursor types distribution:", cursorTypes);
+
+		// Analyze event types
+		const eventTypes = {};
+		data.forEach((item) => {
+			eventTypes[item.type] = (eventTypes[item.type] || 0) + 1;
+		});
+
+		console.log("Event types distribution:", eventTypes);
+	}, 10000);
+}
+
+trackUserInteraction();
+```
+
+### Combined Screen Recording + Cursor Tracking
+
+```javascript
+const recorder = new MacRecorder();
+
+async function recordWithCursorTracking() {
+	// Start both screen recording and cursor tracking
+	await Promise.all([
+		recorder.startRecording("./screen-recording.mov", {
+			captureCursor: false, // Don't show cursor in video
+			includeSystemAudio: true,
+			quality: "high",
+		}),
+		recorder.startCursorTracking("./cursor-data.json"),
+	]);
+
+	console.log("Recording screen and tracking cursor...");
+
+	// Record for 30 seconds
+	setTimeout(async () => {
+		await Promise.all([
+			recorder.stopRecording(),
+			recorder.stopCursorTracking(),
+		]);
+
+		console.log("Screen recording and cursor tracking completed!");
+		console.log("Files created:");
+		console.log("- screen-recording.mov");
+		console.log("- cursor-data.json");
+	}, 30000);
+}
+
+recordWithCursorTracking();
+```
+
 ## Integration Examples
 
 ### Electron Integration
@@ -484,6 +729,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ### Latest Updates
 
+- ✅ **Cursor Tracking**: Track mouse position, cursor types, and click events with JSON export
 - ✅ **Window Recording**: Automatic coordinate conversion for multi-display setups
 - ✅ **Audio Controls**: Separate microphone and system audio controls
 - ✅ **Display Selection**: Multi-monitor support with automatic detection

package/binding.gyp

@@ -5,7 +5,8 @@
       "sources": [
         "src/mac_recorder.mm",
         "src/screen_capture.mm",
-        "src/audio_capture.mm"
+        "src/audio_capture.mm",
+        "src/cursor_tracker.mm"
       ],
       "include_dirs": [
         "<!@(node -p \"require('node-addon-api').include\")"
@@ -30,7 +31,10 @@
           "-framework CoreVideo",
           "-framework Foundation",
           "-framework AppKit",
-          "-framework ScreenCaptureKit"
+          "-framework ScreenCaptureKit",
+          "-framework ApplicationServices",
+          "-framework Carbon",
+          "-framework Accessibility"
         ]
       },
       "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ]

package/cursor-test.js

@@ -0,0 +1,176 @@
+const MacRecorder = require("./index");
+const path = require("path");
+const fs = require("fs");
+
+async function testCursorTracking() {
+	console.log("🎯 Cursor Tracking Test Başlatılıyor...\n");
+
+	const recorder = new MacRecorder();
+
+	try {
+		// Cursor tracking başlat
+		const outputPath = path.join(__dirname, "cursor-data.json");
+		console.log("📍 Cursor tracking başlatılıyor...");
+		console.log("📁 Output dosyası:", outputPath);
+
+		await recorder.startCursorTracking(outputPath);
+		console.log("✅ Cursor tracking başlatıldı!");
+
+		// Durum kontrolü
+		const status = recorder.getCursorTrackingStatus();
+		console.log("📊 Tracking durumu:", status);
+
+		// 5 saniye bekle ve pozisyon örnekleri al
+		console.log(
+			"\n🎬 5 saniye boyunca cursor hareketlerinizi takip ediyoruz..."
+		);
+		console.log("💡 Fare hareket ettirin, tıklayın ve sürükleyin!");
+
+		// Manuel data collection - JavaScript tarafında polling
+		const manualData = [];
+		const startTime = Date.now();
+
+		for (let i = 5; i > 0; i--) {
+			console.log(`⏳ ${i} saniye kaldı...`);
+
+			// 100ms'de bir pozisyon al (10 FPS)
+			for (let j = 0; j < 10; j++) {
+				const position = recorder.getCursorPosition();
+				const timestamp = Date.now() - startTime;
+
+				manualData.push({
+					x: position.x,
+					y: position.y,
+					timestamp: timestamp,
+					cursorType: position.cursorType,
+					type: "move",
+				});
+
+				await new Promise((resolve) => setTimeout(resolve, 100));
+			}
+
+			// Son pozisyonu göster
+			if (manualData.length > 0) {
+				const lastPos = manualData[manualData.length - 1];
+				console.log(
+					`📌 Pozisyon: x=${lastPos.x}, y=${lastPos.y}, tip=${lastPos.cursorType}`
+				);
+			}
+		}
+
+		// Manuel veriyi dosyaya kaydet
+		console.log(
+			`\n📝 Manuel data collection: ${manualData.length} pozisyon toplandı`
+		);
+		const manualPath = path.join(__dirname, "manual-cursor-data.json");
+		fs.writeFileSync(manualPath, JSON.stringify(manualData, null, 2));
+		console.log(`📄 Manuel veriler kaydedildi: ${manualPath}`);
+
+		// Tracking durdur
+		console.log("\n🛑 Cursor tracking durduruluyor...");
+		await recorder.stopCursorTracking();
+		console.log("✅ Cursor tracking durduruldu!");
+
+		// Final durum kontrolü
+		const finalStatus = recorder.getCursorTrackingStatus();
+		console.log("📊 Final durumu:", finalStatus);
+
+		// Dosya kontrolü
+		if (fs.existsSync(outputPath)) {
+			const data = JSON.parse(fs.readFileSync(outputPath, "utf8"));
+			console.log(
+				`\n📄 JSON dosyası oluşturuldu: ${data.length} adet cursor verisi kaydedildi`
+			);
+
+			// İlk birkaç veriyi göster
+			if (data.length > 0) {
+				console.log("\n📝 İlk 3 cursor verisi:");
+				data.slice(0, 3).forEach((item, index) => {
+					console.log(
+						`${index + 1}. x:${item.x}, y:${item.y}, timestamp:${
+							item.timestamp
+						}, cursorType:${item.cursorType}, type:${item.type}`
+					);
+				});
+
+				if (data.length > 3) {
+					console.log(`... ve ${data.length - 3} adet daha`);
+				}
+			}
+
+			// Cursor tipleri istatistiği
+			const cursorTypes = {};
+			const eventTypes = {};
+			data.forEach((item) => {
+				cursorTypes[item.cursorType] = (cursorTypes[item.cursorType] || 0) + 1;
+				eventTypes[item.type] = (eventTypes[item.type] || 0) + 1;
+			});
+
+			console.log("\n📈 Cursor Tipleri İstatistiği:");
+			Object.keys(cursorTypes).forEach((type) => {
+				console.log(`  ${type}: ${cursorTypes[type]} adet`);
+			});
+
+			console.log("\n🎭 Event Tipleri İstatistiği:");
+			Object.keys(eventTypes).forEach((type) => {
+				console.log(`  ${type}: ${eventTypes[type]} adet`);
+			});
+		} else {
+			console.log("❌ JSON dosyası oluşturulamadı!");
+		}
+	} catch (error) {
+		console.error("❌ Hata:", error.message);
+	}
+
+	console.log("\n🎉 Test tamamlandı!");
+}
+
+// Ek fonksiyonlar test et
+async function testCursorPositionOnly() {
+	console.log("\n🎯 Anlık Cursor Pozisyon Testi...");
+
+	const recorder = new MacRecorder();
+
+	try {
+		for (let i = 0; i < 5; i++) {
+			const position = recorder.getCursorPosition();
+			console.log(
+				`📌 Pozisyon ${i + 1}: x=${position.x}, y=${position.y}, tip=${
+					position.cursorType
+				}`
+			);
+			await new Promise((resolve) => setTimeout(resolve, 500));
+		}
+	} catch (error) {
+		console.error("❌ Pozisyon alma hatası:", error.message);
+	}
+}
+
+// Test menüsü
+async function main() {
+	console.log("🚀 MacRecorder Cursor Tracking Test Menüsü\n");
+
+	const args = process.argv.slice(2);
+
+	if (args.includes("--position")) {
+		await testCursorPositionOnly();
+	} else if (args.includes("--full")) {
+		await testCursorTracking();
+	} else {
+		console.log("Kullanım:");
+		console.log(
+			"  node cursor-test.js --full     # Tam cursor tracking testi (5 saniye)"
+		);
+		console.log(
+			"  node cursor-test.js --position # Sadece anlık pozisyon testi"
+		);
+		console.log("\nÖrnek:");
+		console.log("  node cursor-test.js --full");
+	}
+}
+
+if (require.main === module) {
+	main().catch(console.error);
+}
+
+module.exports = { testCursorTracking, testCursorPositionOnly };

package/index.js

@@ -355,6 +355,154 @@ class MacRecorder extends EventEmitter {
 		});
 	}
 
+	/**
+	 * Pencere önizleme görüntüsü alır (Base64 PNG)
+	 */
+	async getWindowThumbnail(windowId, options = {}) {
+		if (!windowId) {
+			throw new Error("Window ID is required");
+		}
+
+		const { maxWidth = 300, maxHeight = 200 } = options;
+
+		return new Promise((resolve, reject) => {
+			try {
+				const base64Image = nativeBinding.getWindowThumbnail(
+					windowId,
+					maxWidth,
+					maxHeight
+				);
+
+				if (base64Image) {
+					resolve(`data:image/png;base64,${base64Image}`);
+				} else {
+					reject(new Error("Failed to capture window thumbnail"));
+				}
+			} catch (error) {
+				reject(error);
+			}
+		});
+	}
+
+	/**
+	 * Ekran önizleme görüntüsü alır (Base64 PNG)
+	 */
+	async getDisplayThumbnail(displayId, options = {}) {
+		if (displayId === null || displayId === undefined) {
+			throw new Error("Display ID is required");
+		}
+
+		const { maxWidth = 300, maxHeight = 200 } = options;
+
+		return new Promise((resolve, reject) => {
+			try {
+				const base64Image = nativeBinding.getDisplayThumbnail(
+					displayId,
+					maxWidth,
+					maxHeight
+				);
+
+				if (base64Image) {
+					resolve(`data:image/png;base64,${base64Image}`);
+				} else {
+					reject(new Error("Failed to capture display thumbnail"));
+				}
+			} catch (error) {
+				reject(error);
+			}
+		});
+	}
+
+	/**
+	 * Cursor tracking başlatır
+	 */
+	async startCursorTracking(outputPath) {
+		if (!outputPath) {
+			throw new Error("Output path is required");
+		}
+
+		return new Promise((resolve, reject) => {
+			try {
+				const success = nativeBinding.startCursorTracking(outputPath);
+				if (success) {
+					this.emit("cursorTrackingStarted", outputPath);
+					resolve(true);
+				} else {
+					reject(
+						new Error(
+							"Failed to start cursor tracking. Check permissions and try again."
+						)
+					);
+				}
+			} catch (error) {
+				reject(error);
+			}
+		});
+	}
+
+	/**
+	 * Cursor tracking durdurur ve JSON dosyasını kaydeder
+	 */
+	async stopCursorTracking() {
+		return new Promise((resolve, reject) => {
+			try {
+				const success = nativeBinding.stopCursorTracking();
+				if (success) {
+					this.emit("cursorTrackingStopped");
+					resolve(true);
+				} else {
+					reject(new Error("Failed to stop cursor tracking"));
+				}
+			} catch (error) {
+				reject(error);
+			}
+		});
+	}
+
+	/**
+	 * Anlık cursor pozisyonunu ve tipini döndürür
+	 */
+	getCursorPosition() {
+		try {
+			return nativeBinding.getCursorPosition();
+		} catch (error) {
+			throw new Error("Failed to get cursor position: " + error.message);
+		}
+	}
+
+	/**
+	 * Cursor tracking durumunu döndürür
+	 */
+	getCursorTrackingStatus() {
+		try {
+			return nativeBinding.getCursorTrackingStatus();
+		} catch (error) {
+			throw new Error("Failed to get cursor tracking status: " + error.message);
+		}
+	}
+
+	/**
+	 * Cursor verilerini JSON dosyasına kaydeder
+	 */
+	async saveCursorData(outputPath) {
+		if (!outputPath) {
+			throw new Error("Output path is required");
+		}
+
+		return new Promise((resolve, reject) => {
+			try {
+				const success = nativeBinding.saveCursorData(outputPath);
+				if (success) {
+					resolve(true);
+				} else {
+					reject(new Error("Failed to save cursor data"));
+				}
+			} catch (error) {
+				reject(error);
+			}
+		});
+	}
+
 	/**
 	 * Native modül bilgilerini döndürür
 	 */