feat: add converFrame to convert the ascii output from https://www.ascii-animator.com/ (#5)

Author: Lanznx

README.md

@@ -75,10 +75,93 @@ except KeyboardInterrupt:
     lazy.stop()
 ```
 
+## 🎬 Adding Custom Animations
+
+LazyB supports ASCII animations that play while keeping your status active. You can add your own custom animations to the system.
+
+### Animation File Structure
+
+Animations are stored in the `animations` directory, with each animation in its own subdirectory. Each frame should be saved as a separate `.txt` file with a numbered sequence.
+
+**Supported naming formats:**
+- `frame_1.txt`, `frame_2.txt`, `frame_3.txt`, ... (frame_NUMBER.txt)
+- `001_description.txt`, `002_description.txt`, `003_description.txt`, ... (NUMBER_description.txt)
+
+**Example structure:**
+```
+animations/
+├── my_cool_animation/
+│   ├── frame_1.txt
+│   ├── frame_2.txt
+│   └── frame_3.txt
+└── another_animation/
+    ├── 001_start.txt
+    ├── 002_middle.txt
+    └── 003_end.txt
+```
+
+### Creating Animations from Videos
+
+If you want to convert a video into ASCII animation, follow these steps:
+
+#### Step 1: Convert Video to ASCII Frames
+
+1. **Clone the ASCII Animator tool:**
+   ```bash
+   git clone https://github.com/bradysheridan/ascii-animator.git
+   cd ascii-animator
+   ```
+
+2. **Upload your video file** to the ASCII Animator and process it through their system.
+
+3. **Export the output** - you should get a `frames.js` file containing an array of ASCII frames.
+
+#### Step 2: Convert Frames to TXT Files
+
+1. **Place the `frames.js` file** in your LazyB `animations` directory.
+
+2. **Run the conversion script** (requires Node.js):
+   ```bash
+   # Install Node.js if not already installed
+   # Visit https://nodejs.org/ or use package manager
+   
+   cd animations
+   node convertFramesToTxt.js
+   ```
+
+3. **Follow the prompts** to name your animation directory (avoid spaces and special characters).
+
+4. **The script will create** a new directory with all frames converted to individual `.txt` files.
+
+#### Step 3: Test Your Animation
+
+1. **Run LazyB** and your new animation should appear in the selection menu:
+   ```bash
+   lazy-b
+   ```
+
+2. **Use arrow keys** to navigate and select your animation.
+
+### Animation Guidelines
+
+- **File naming**: Frames must be numbered sequentially starting from 1
+- **File format**: Plain text (`.txt`) files with UTF-8 encoding
+- **Frame size**: Recommended maximum 80 characters wide for terminal compatibility
+- **Frame rate**: Default is 0.2 seconds per frame (5 FPS), configurable
+- **Directory naming**: Use underscores instead of spaces, avoid special characters
+
+### Troubleshooting
+
+- **Animation not showing up?** Check that frame files follow the naming convention
+- **Frames out of order?** Ensure sequential numbering without gaps
+- **Display issues?** Verify files are UTF-8 encoded and frames aren't too wide
+
 ## Features
 
 - Prevents "away" or "inactive" status in messaging applications
-- Customizable interval between key presses (default: 1 second)
+- **🎬 ASCII Animation Support**: Display entertaining animations while keeping your status active
+- Interactive animation selection menu with live preview
+- Customizable interval between key presses (default: 3 minutes)
 - Simple command-line interface
 - Cross-platform: Works on macOS, Windows, and Linux
 - Background mode on macOS (no dock icon)
@@ -121,10 +204,15 @@ Pushing a tag will automatically trigger the release workflow, which will:
 
 ## Requirements
 
+### Runtime Requirements
 - Python 3.8 or higher
 - PyAutoGUI
 - PyObjC-Core (for macOS dock icon hiding, optional)
 
+### Animation Development Requirements (Optional)
+- Node.js (for running the frame conversion script)
+- Access to [ASCII Animator](https://github.com/bradysheridan/ascii-animator) for video-to-ASCII conversion
+
 ## License
 
 MIT

animations/convertFramesToTxt.js

@@ -0,0 +1,85 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+
+// Get __dirname equivalent in ES modules
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Import frames from frames.js
+import { frames } from './frames.js';
+
+// Create readline interface for user input
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+// Function to validate directory name
+function validateDirectoryName(name) {
+  // Check for invalid characters (spaces, special characters that might cause issues)
+  const invalidChars = /[<>:"/\\|?*\s]/;
+  if (invalidChars.test(name)) {
+    return false;
+  }
+  // Check if name is not empty
+  if (!name.trim()) {
+    return false;
+  }
+  return true;
+}
+
+// Function to prompt user for directory name
+function promptForDirectoryName() {
+  return new Promise((resolve) => {
+    rl.question('請輸入動畫資料夾名稱 (不能包含空格或特殊字元): ', (answer) => {
+      const trimmedAnswer = answer.trim();
+      if (validateDirectoryName(trimmedAnswer)) {
+        resolve(trimmedAnswer);
+      } else {
+        console.log('❌ 無效的資料夾名稱！請避免使用空格和特殊字元 (<>:"/\\|?*)');
+        promptForDirectoryName().then(resolve);
+      }
+    });
+  });
+}
+
+// Main execution
+async function main() {
+  try {
+    console.log('🎬 Frame to TXT 轉換工具');
+    console.log(`📊 共找到 ${frames.length} 個影格`);
+
+    const directoryName = await promptForDirectoryName();
+    const outputDir = path.join(__dirname, directoryName);
+
+    // Ensure the output directory exists
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir);
+      console.log(`📁 已建立資料夾: ${directoryName}`);
+    } else {
+      console.log(`📁 使用現有資料夾: ${directoryName}`);
+    }
+
+    // Convert each frame to a .txt file
+    console.log('🔄 開始轉換 Frames...');
+    frames.forEach((frame, index) => {
+      const fileName = `frame_${index + 1}.txt`;
+      const filePath = path.join(outputDir, fileName);
+
+      fs.writeFileSync(filePath, frame, 'utf8');
+      console.log(`✅ 已儲存: ${fileName}`);
+    });
+
+    console.log(`🎉 所有 Frames 已成功轉換為 .txt 檔案！`);
+    console.log(`📍 檔案位置: ${outputDir}`);
+
+  } catch (error) {
+    console.error('❌ 轉換過程中發生錯誤:', error.message);
+  } finally {
+    rl.close();
+  }
+}
+
+main();