4 |
5 | 📡 DeckTap is a lightweight local-network remote for controlling presentations.
6 | Use your phone to wirelessly control PowerPoint, Keynote, PDF slideshows — no app installation needed.
7 |
8 | ---
9 |
10 | ## ✨ Features
11 |
12 | - 📱 Control slides via your phone browser
13 | - 🌐 Works over local Wi-Fi/Hotspot network
14 | - 🖥 Simulates keyboard arrow keys to navigate slides
15 | - 🚀 Minimal setup: run a local Node.js server and scan a QR code
16 | - 🔒 No internet required, **safe** and **private**
17 |
18 | ---
19 |
20 | ## 📦 Project Structure
21 | ```yaml
22 | decktap/
23 | ├── client/ # Computer side agent
24 | │ ├── lan.js # LAN control
25 | │ ├── cloud.js # Connect cloud relay server in the future
26 | │ └── config.js
27 | │
28 | ├── controller/ # Mobile phone controller web page
29 | │ └── index.html
30 | │
31 | ├── server-cloud/ # Cloud server for remote control in the future
32 | │ └── server.js
33 | │
34 | ├── README.md
35 | ├── LICENSE
36 | ├── package.json
37 | └── .gitignore
38 | ```
39 | ---
40 |
41 | ## 🔧 Prerequisites
42 |
43 | ### macOS Permissions
44 | DeckTap uses `@nut-tree/nut-js` to simulate keyboard events. On macOS, you need to grant Accessibility permissions to your terminal:
45 |
46 | 1. Open **System Settings** > **Privacy & Security** > **Accessibility**
47 | 2. Click the lock icon 🔒 to make changes
48 | 3. Click the **+** button
49 | 4. Select `Terminal.app` (or iTerm, VS Code, etc. depending on what you use)
50 | 5. Check the box next to your terminal app
51 |
52 | > **Note**: Without these permissions, DeckTap won't be able to control your presentations.
53 |
54 | ---
55 |
56 | ## 🚀 Getting Started (LAN Mode)
57 | 1. Install dependencies:
58 | ```bash
59 | cd decktap-web && npm install && npm run build
60 | cd .. && npm install
61 | ```
62 |
63 | 2. Grant accessibility permissions (macOS only):
64 | - Follow the steps in [macOS Permissions](#macos-permissions)
65 | - Restart your terminal after granting permissions
66 |
67 | 3. Start the server:
68 | ```bash
69 | npm start
70 | ```
71 |
72 | 4. Connect with your phone:
73 | - Connect your phone to the same WiFi network(only support private WiFi without vlan, not working on campus network) as your computer
74 | - Open the displayed URL in your phone's browser or Scan the QR code
75 | - 
76 | - Start controlling your presentation (Use 👉 to switch left and right hand mode)
77 | - 
78 |
79 |
80 | ---
81 |
82 | ## ~🖱️ Standalone Distribution Quick Start~ (Not available yet, an Electron client will be developed in the future)
83 |
84 | If you received a **standalone executable version** of DeckTap (such as `decktap-macos`, `decktap-win.exe`, or `decktap-linux`), you can run it directly without installing Node.js or any dependencies.
85 |
86 | ### Steps
87 | 1. **macOS / Linux users:**
88 | - Before the first run, grant execute permission (only needed once):
89 | ```bash
90 | chmod +x decktap-macos
91 | ```
92 | - Run:
93 | ```bash
94 | ./decktap-macos
95 | ```
96 | 2. **Windows users:**
97 | - Run it in the command prompt:
98 | ```bat
99 | decktap-win.exe
100 | ```
101 | 3. **First run on macOS:** Please follow the terminal prompts to grant Accessibility permissions (see above [macOS Permissions](#macos-permissions)).
102 |
103 | 4. **Scan the QR code or open the displayed URL on your phone to start controlling your presentation!**
104 |
105 | ---
106 |
107 | > If you encounter issues such as failure to run, insufficient permissions, or cannot access the page, please send the terminal error message to the developer for help.
108 |
--------------------------------------------------------------------------------
/client/lan.js:
--------------------------------------------------------------------------------
1 | const express = require('express');
2 | const http = require('http');
3 | const WebSocket = require('ws');
4 | const { keyboard, Key } = require("@nut-tree/nut-js");
5 | const os = require('os');
6 | const qrcode = require('qrcode-terminal');
7 | const path = require('path');
8 |
9 | const app = express();
10 | const server = http.createServer(app);
11 | const wss = new WebSocket.Server({ server });
12 | const port = 9999;
13 |
14 | const staticPath = path.join(__dirname, '..', 'decktap-web', 'dist');
15 |
16 | console.log('📂 Static files path:', staticPath);
17 | app.use(express.static(staticPath));
18 |
19 | // WebSocket 连接处理
20 | wss.on('connection', (ws) => {
21 | console.log('📲 Mobile phone controller connected');
22 | ws.on('message', (message) => {
23 | const msg = message.toString();
24 | console.log('🔍 Received message:', msg);
25 | if (msg === 'next') {
26 | try {
27 | (async () => {
28 | await keyboard.pressKey(Key.Right);
29 | await keyboard.releaseKey(Key.Right);
30 | })();
31 | } catch (error) {
32 | console.error('❌ Key simulation failed:', error);
33 | }
34 | } else if (msg === 'prev') {
35 | try {
36 | (async () => {
37 | await keyboard.pressKey(Key.Left);
38 | await keyboard.releaseKey(Key.Left);
39 | })();
40 | } catch (error) {
41 | console.error('❌ Key simulation failed:', error);
42 | }
43 | } else {
44 | console.log('❌ Unknown message type:', msg);
45 | }
46 | });
47 |
48 | ws.on('error', (error) => {
49 | console.error('❌ WebSocket error:', error);
50 | });
51 |
52 | ws.on('close', () => {
53 | console.log('🔌 The phone controller has been disconnected');
54 | });
55 | });
56 |
57 | server.listen(port, () => {
58 | const controlUrl = `http://${getLocalIP()}:${port}`;
59 | console.log(`\n✅ DeckTap LAN service has been started：${controlUrl}`);
60 | console.log('\n🔗 Please open the above link with your mobile phone under the same Wi-Fi, or scan the QR code below:\n');
61 | qrcode.generate(controlUrl, { small: true });
62 | });
63 |
64 | process.on('SIGINT', () => {
65 | ioHook.unload();
66 | ioHook.stop();
67 | process.exit();
68 | });
69 |
70 | function getLocalIP() {
71 | const interfaces = os.networkInterfaces();
72 | console.log('🔍 Scanning the network interface......');
73 |
74 | // 存储所有找到的 IP 地址
75 | const ipAddresses = [];
76 |
77 | for (let [name, iface] of Object.entries(interfaces)) {
78 | for (let config of iface) {
79 | if (config.family === 'IPv4' && !config.internal) {
80 | // 检查是否是有效的单播地址（不是网络地址或广播地址）
81 | const ipParts = config.address.split('.').map(Number);
82 | const lastOctet = ipParts[3];
83 | if (lastOctet !== 0 && lastOctet !== 255) { // 排除网络地址和广播地址
84 | console.log(`📡 Discover network interfaces: ${name}`);
85 | console.log(` IP Address: ${config.address}`);
86 | console.log(` Subnet Mask: ${config.netmask}`);
87 | ipAddresses.push({
88 | name,
89 | address: config.address,
90 | netmask: config.netmask,
91 | // 添加优先级分数
92 | priority: getPriorityScore(config.address, name)
93 | });
94 | }
95 | }
96 | }
97 | }
98 |
99 | // 按优先级排序
100 | ipAddresses.sort((a, b) => b.priority - a.priority);
101 |
102 | if (ipAddresses.length > 0) {
103 | const selectedIP = ipAddresses[0];
104 | console.log(`✅ Choose Local IP: ${selectedIP.address} (${selectedIP.name})`);
105 | return selectedIP.address;
106 | }
107 |
108 | console.log('❌ No available network interface was found, use localhost');
109 | return 'localhost';
110 | }
111 |
112 | // 计算 IP 地址的优先级分数
113 | function getPriorityScore(address, interfaceName) {
114 | let score = 0;
115 |
116 | // 优先选择常见的本地网络接口名称
117 | if (interfaceName.includes('en0') || interfaceName.includes('wlan0')) {
118 | score += 100;
119 | }
120 |
121 | // 优先选择 192.168.x.x 地址（最常见的本地网络）
122 | if (address.startsWith('192.168.')) {
123 | score += 50;
124 | }
125 |
126 | // 优先选择 172.16.x.x - 172.31.x.x 地址
127 | if (address.startsWith('172.')) {
128 | const secondOctet = parseInt(address.split('.')[1]);
129 | if (secondOctet >= 16 && secondOctet <= 31) {
130 | score += 40;
131 | }
132 | }
133 |
134 | // 优先选择 10.x.x.x 地址
135 | if (address.startsWith('10.')) {
136 | score += 30;
137 | }
138 |
139 | // 排除一些特殊的网络接口
140 | if (interfaceName.includes('vmnet') ||
141 | interfaceName.includes('docker') ||
142 | interfaceName.includes('veth')) {
143 | score -= 100;
144 | }
145 |
146 | return score;
147 | }
148 |
--------------------------------------------------------------------------------
/decktap-web/.gitignore:
--------------------------------------------------------------------------------
1 | # Logs
2 | logs
3 | *.log
4 | npm-debug.log*
5 | yarn-debug.log*
6 | yarn-error.log*
7 | pnpm-debug.log*
8 | lerna-debug.log*
9 |
10 | node_modules
11 | dist
12 | dist-ssr
13 | *.local
14 |
15 | # Editor directories and files
16 | .vscode/*
17 | !.vscode/extensions.json
18 | .idea
19 | .DS_Store
20 | *.suo
21 | *.ntvs*
22 | *.njsproj
23 | *.sln
24 | *.sw?
25 |
--------------------------------------------------------------------------------
/decktap-web/README.md:
--------------------------------------------------------------------------------
1 | # React + TypeScript + Vite
2 |
3 | This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
4 |
5 | Currently, two official plugins are available:
6 |
7 | - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
8 | - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
9 |
10 | ## Expanding the ESLint configuration
11 |
12 | If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
13 |
14 | ```js
15 | export default tseslint.config({
16 | extends: [
17 | // Remove ...tseslint.configs.recommended and replace with this
18 | ...tseslint.configs.recommendedTypeChecked,
19 | // Alternatively, use this for stricter rules
20 | ...tseslint.configs.strictTypeChecked,
21 | // Optionally, add this for stylistic rules
22 | ...tseslint.configs.stylisticTypeChecked,
23 | ],
24 | languageOptions: {
25 | // other options...
26 | parserOptions: {
27 | project: ['./tsconfig.node.json', './tsconfig.app.json'],
28 | tsconfigRootDir: import.meta.dirname,
29 | },
30 | },
31 | })
32 | ```
33 |
34 | You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
35 |
36 | ```js
37 | // eslint.config.js
38 | import reactX from 'eslint-plugin-react-x'
39 | import reactDom from 'eslint-plugin-react-dom'
40 |
41 | export default tseslint.config({
42 | plugins: {
43 | // Add the react-x and react-dom plugins
44 | 'react-x': reactX,
45 | 'react-dom': reactDom,
46 | },
47 | rules: {
48 | // other rules...
49 | // Enable its recommended typescript rules
50 | ...reactX.configs['recommended-typescript'].rules,
51 | ...reactDom.configs.recommended.rules,
52 | },
53 | })
54 | ```
55 |
--------------------------------------------------------------------------------
/decktap-web/eslint.config.js:
--------------------------------------------------------------------------------
1 | import js from '@eslint/js'
2 | import globals from 'globals'
3 | import reactHooks from 'eslint-plugin-react-hooks'
4 | import reactRefresh from 'eslint-plugin-react-refresh'
5 | import tseslint from 'typescript-eslint'
6 |
7 | export default tseslint.config(
8 | { ignores: ['dist'] },
9 | {
10 | extends: [js.configs.recommended, ...tseslint.configs.recommended],
11 | files: ['**/*.{ts,tsx}'],
12 | languageOptions: {
13 | ecmaVersion: 2020,
14 | globals: globals.browser,
15 | },
16 | plugins: {
17 | 'react-hooks': reactHooks,
18 | 'react-refresh': reactRefresh,
19 | },
20 | rules: {
21 | ...reactHooks.configs.recommended.rules,
22 | 'react-refresh/only-export-components': [
23 | 'warn',
24 | { allowConstantExport: true },
25 | ],
26 | },
27 | },
28 | )
29 |
--------------------------------------------------------------------------------
/decktap-web/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |