Type-Simulator is a versatile Python tool for automating human-like typing in any text editor or input field. Whether you're creating demos, running automated tutorials, or stress-testing text-based applications, Type-Simulator lets you control keyboard inputs with precision and randomness for a natural effect.
- 5 New Typing Profiles:
programmer,storyteller,casual,expert,nervous - Enhanced Macro System: New commands including
{DATE},{TIME},{DATETIME},{COUNTER},{LOOP},{NL},{TAB} - Improved Statistics: Detailed character breakdown with emoji indicators
- Headless Direct Mode: Now works without DISPLAY environment variable
- Better CLI Experience: Enhanced help output with examples and profile details
- What's New
- Features
- System Requirements
- Installation
- Quick Start
- Usage
- Typing Modes
- Typing Profiles
- Macro Commands
- Build & Distribution
- Advanced Usage
- Troubleshooting
- Contributing
- License
- Human-Like Typing: Configurable speed and variance simulate real typing habits
- 10 Typing Profiles: Pre-built profiles for different scenarios including human, fast, slow, robotic, programmer, expert, and more
- Editor Agnostic: Works with any text editor or input field
- Flexible Input: Accept text from command line, files, or STDIN
- Multiple Modes:
- GUI Mode: Drive a full editor (e.g., vim, gedit) under Xvfb for headless CI
- Terminal Mode: Open a terminal emulator for shell-driven typing
- Direct Mode: Write text straight to a file without a GUI (no DISPLAY required)
- Focus Mode: Type directly into the currently focused window
- Powerful Macro System: Support for repeat blocks, loops, random text, speed changes, variables, waits, mouse actions, key combinations, date/time, counters, and formatting
- Statistics: Get detailed typing statistics including WPM, character breakdown, and duration
- Dry Run: Validate input without executing actions
- Verbose Logging: Adjustable log levels (DEBUG, INFO, WARNING, ERROR) for troubleshooting
- Python: 3.7 or higher
- Operating System: Linux, macOS, or Windows
- For GUI/Terminal modes on Linux:
xvfb- Virtual framebuffer for headless operationxterm- Terminal emulator (default)xdotool- X11 automation toolxfonts-base- Basic X11 fonts
git clone https://github.com/djeada/Type-Simulator.git
cd Type-Simulatorpip install -r requirements.txtKey dependencies include:
- PyAutoGUI - Cross-platform GUI automation
- python3-xlib - Python X11 library (Linux)
- Pillow - Python Imaging Library
- pyperclip - Clipboard access
- PyGetWindow, PyMsgBox, PyRect, PyScreeze - GUI automation components
- pytweening - Tweening/easing functions
- MouseInfo - Mouse position information
See requirements.txt for the complete list of dependencies.
For GUI and terminal modes on Linux, install these system packages:
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y xvfb xterm xdotool xfonts-base
# Fedora/RHEL
sudo dnf install -y xorg-x11-server-Xvfb xterm xdotool xorg-x11-fonts-misc
# Arch Linux
sudo pacman -S xorg-server-xvfb xterm xdotool xorg-fonts-miscHere's the simplest way to get started:
# Write "Hello, World!" to a file
python -m src.main --mode direct --output hello.txt --input "Hello, World!"
# Type into the currently focused window
python -m src.main --mode focus --input "This text will be typed!"
# Use a typing profile for natural typing
python -m src.main --mode focus --input "Natural typing" --profile human
# Type content from a file
python -m src.main --mode direct --output result.txt --input demo/demo_type_text.txt# Direct mode - Write to file with custom speed
python -m src.main --mode direct --output demo.txt --input "Hello, World!" --speed 0.1
# Focus mode - Type into active window with a profile
python -m src.main --mode focus --input "Fast typing demo" --profile fast
# Terminal mode - Execute shell commands
python -m src.main --mode terminal --input "ls -la"
# GUI mode - Open an editor and type
python -m src.main --mode gui --editor-script "gedit" --input "Text in gedit"
# Read from STDIN (pipe mode)
echo "Piped text" | python -m src.main --mode direct --output output.txt
# Show statistics after typing
python -m src.main --mode direct --output demo.txt --input "Test text" --stats
# Dry run - Validate without executing
python -m src.main --mode direct --output demo.txt --input "{REPEAT_3}Test{/REPEAT}" --dry-run
# List available profiles
python -m src.main --list-profilesusage: type_simulator [-h] [-e EDITOR_SCRIPT] [--mode {gui,terminal,direct,focus}]
[-s SPEED] [-v VARIANCE] [-p PROFILE] [-i INPUT] [-o OUTPUT]
[--log-level {DEBUG,INFO,WARNING,ERROR}] [-w WAIT]
[--pre-launch-cmd CMD] [-V] [--dry-run] [--stats]
[--list-profiles]
Options:
-h, --help Show help message and exit
-e, --editor-script Command to open the editor (default: 'xterm -e vi')
--mode Typing mode: gui, terminal, direct, or focus
-s, --speed Typing speed in seconds per character
-v, --variance Random variation in typing speed
-p, --profile Use a preset typing profile
-i, --input Input text or file path to type
-o, --output Output file path (required for direct mode)
--log-level Logging verbosity (default: INFO)
-w, --wait Seconds to wait after typing before closing
--pre-launch-cmd Command to run before typing starts
-V, --version Show version and exit
--dry-run Validate input without executing
--stats Show typing statistics after completion
--list-profiles List available typing profiles
Type-Simulator supports four different typing modes:
Writes text directly to a file without any GUI interaction. Fastest mode, ideal for generating text files.
Required: --output flag to specify destination file
python -m src.main --mode direct --output result.txt --input "Direct write"Types into the currently focused window using platform-specific automation tools. Works across different applications and platforms.
Best for: Live demos, presentations, automated data entry
python -m src.main --mode focus --input "Types into active window"Opens a terminal emulator and types the input as shell commands. Useful for automating command-line operations.
Best for: Shell command demonstrations, CLI tutorials
python -m src.main --mode terminal --input "echo 'Hello from terminal!'"Launches a full text editor and types into it. Can run headlessly using Xvfb for CI/CD pipelines.
Best for: Editor-specific demonstrations, vim tutorials, headless CI testing
python -m src.main --mode gui --editor-script "gedit" --input "Text in editor"
python -m src.main --mode gui --editor-script "xterm -e vim" --input "Vim commands"Type-Simulator includes pre-configured typing profiles that simulate different typing styles:
| Profile | Speed | Variance | Description |
|---|---|---|---|
human |
0.08s | Β±0.04 | Natural human typing with realistic variations |
fast |
0.03s | Β±0.01 | Quick professional typing |
slow |
0.2s | Β±0.08 | Careful, deliberate typing |
robotic |
0.05s | 0.0 | Mechanical, consistent typing with no variance |
hunt_and_peck |
0.4s | Β±0.2 | Slow, searching for keys typing style |
programmer |
0.05s | Β±0.03 | Fast typing with thinking pauses for coding |
storyteller |
0.1s | Β±0.05 | Dramatic typing with pauses for effect |
casual |
0.12s | Β±0.08 | Relaxed, informal typing rhythm |
expert |
0.02s | Β±0.005 | Ultra-fast professional touch typist |
nervous |
0.06s | Β±0.04 | Quick bursts with frequent hesitations |
Usage:
# Use a profile
python -m src.main --mode focus --input "Natural typing" --profile human
# Override profile settings with custom speed/variance
python -m src.main --mode focus --input "Custom" --profile human --speed 0.05 --variance 0.02
# List all available profiles
python -m src.main --list-profilesType-Simulator supports a powerful macro system for advanced automation. Macros are enclosed in curly braces {}.
Repeat a block of text multiple times.
Syntax: {REPEAT_N}...text...{/REPEAT}
# Output: "Hello Hello Hello "
python -m src.main --mode focus --input "{REPEAT_3}Hello {/REPEAT}"
# Nested example
python -m src.main --mode focus --input "{REPEAT_2}Line {REPEAT_3}* {/REPEAT}{/REPEAT}"
# Output: "Line * * * Line * * * "Generate random text of specified length.
Syntax: {RANDOM_length} or {RANDOM_length_charset}
Charsets: alphanumeric, alpha, numeric, custom:ABC123
# Generate 12 random alphanumeric characters
python -m src.main --mode focus --input "Password: {RANDOM_12}"
# Generate 8 random letters
python -m src.main --mode focus --input "Code: {RANDOM_8_alpha}"
# Generate 6 random numbers
python -m src.main --mode focus --input "PIN: {RANDOM_6_numeric}"
# Custom character set
python -m src.main --mode focus --input "Hex: {RANDOM_16_custom:0123456789ABCDEF}"Pause typing for a specified number of seconds.
Syntax: {WAIT_seconds}
# Wait 2 seconds between actions
python -m src.main --mode focus --input "Step 1{WAIT_2}Step 2{WAIT_1.5}Step 3"
# Wait before typing starts
python -m src.main --mode focus --input "{WAIT_1}Started after 1 second"Change typing speed dynamically during execution.
Syntax: {SPEED_speed} or {SPEED_speed_variance}
# Change speed mid-text
python -m src.main --mode focus --input "{SPEED_0.2}Slow start{SPEED_0.02}Fast finish"
# Speed with variance
python -m src.main --mode focus --input "{SPEED_0.1_0.05}Variable speed typing"Move mouse cursor to specific coordinates.
Syntax: {MOUSE_MOVE_x_y}
# Move mouse to position (500, 300)
python -m src.main --mode focus --input "{MOUSE_MOVE_500_300}"
# Move and click
python -m src.main --mode focus --input "{MOUSE_MOVE_100_200}{WAIT_0.2}{MOUSE_CLICK_left}"Click mouse buttons at current position.
Syntax: {MOUSE_CLICK_button}
Buttons: left, right, middle
# Left click
python -m src.main --mode focus --input "{MOUSE_CLICK_left}"
# Right click for context menu
python -m src.main --mode focus --input "{MOUSE_CLICK_right}"
# Double-click
python -m src.main --mode focus --input "{MOUSE_CLICK_left}{MOUSE_CLICK_left}"
# Complete mouse workflow
python -m src.main --mode focus --input "{MOUSE_MOVE_500_300}{WAIT_0.5}{MOUSE_CLICK_right}{WAIT_0.3}{MOUSE_CLICK_left}"Simulate keyboard shortcuts and special keys.
Syntax: {<key>} or {<modifier>+<key>}
Common Keys: enter, esc, tab, backspace, delete, up, down, left, right, home, end, pageup, pagedown
Modifiers: ctrl, alt, shift, win/cmd
# Press Enter
python -m src.main --mode focus --input "Hello{<enter>}World"
# Keyboard shortcuts
python -m src.main --mode focus --input "{<ctrl>+a}" # Select all
python -m src.main --mode focus --input "{<ctrl>+c}" # Copy
python -m src.main --mode focus --input "{<ctrl>+v}" # Paste
python -m src.main --mode focus --input "{<ctrl>+s}" # Save
# Multiple modifiers
python -m src.main --mode focus --input "{<ctrl>+<shift>+n}" # Ctrl+Shift+N
# Navigation
python -m src.main --mode focus --input "{<home>}Start of line{<end>}"
python -m src.main --mode focus --input "{<up>}{<up>}{<down>}"
# Windows/Mac key
python -m src.main --mode focus --input "{<win>+r}" # Open Run dialog (Windows)
python -m src.main --mode focus --input "{<cmd>+space}" # Spotlight (Mac)# Complete workflow: Open Run, launch cmd, execute command
python -m src.main --mode focus --input "{<win>+r}{WAIT_0.3}cmd{<enter>}{WAIT_1}echo Demo{<enter>}"Store and retrieve values during execution.
Syntax:
- Set:
{SET_name=value} - Get:
{GET_name}
# Set and use a variable
python -m src.main --mode focus --input "{SET_name=World}Hello, {GET_name}!"
# Output: "Hello, World!"
# Multiple variables
python -m src.main --mode focus --input "{SET_user=Alice}{SET_action=logged in}{GET_user} has {GET_action}"
# Output: "Alice has logged in"
# Variables with repeats
python -m src.main --mode focus --input "{SET_msg=Hello }{REPEAT_3}{GET_msg}{/REPEAT}"
# Output: "Hello Hello Hello "Insert current date and time with optional formatting.
Syntax:
- Full datetime:
{DATETIME}or{DATETIME_format} - Date only:
{DATE} - Time only:
{TIME}
# Insert current datetime (YYYY-MM-DD HH:MM:SS)
python -m src.main --mode focus --input "Log entry at {DATETIME}"
# Custom format
python -m src.main --mode focus --input "Today is {DATETIME_%Y/%m/%d}"
# Date only (YYYY-MM-DD)
python -m src.main --mode focus --input "Date: {DATE}"
# Time only (HH:MM:SS)
python -m src.main --mode focus --input "Time: {TIME}"Loop through iterations with an accessible loop variable.
Syntax: {LOOP_N}...text...{/LOOP} or {LOOP_N_varname}...{/LOOP}
# Simple loop (uses default variable 'i')
python -m src.main --mode focus --input "{LOOP_5}Item {GET_i} {/LOOP}"
# Output: "Item 1 Item 2 Item 3 Item 4 Item 5 "
# Loop with custom variable name
python -m src.main --mode focus --input "{LOOP_3_num}Line {GET_num}{NL}{/LOOP}"
# Output: "Line 1\nLine 2\nLine 3\n"Manage sequential counters for auto-numbering.
Syntax: {COUNTER} or {COUNTER_name} or {COUNTER_name_action}
# Simple counter (auto-increments)
python -m src.main --mode focus --input "{COUNTER}. Item A{NL}{COUNTER}. Item B{NL}{COUNTER}. Item C"
# Output: "1. Item A\n2. Item B\n3. Item C"
# Named counter
python -m src.main --mode focus --input "{COUNTER_items}. First{NL}{COUNTER_items}. Second"Insert newlines and tabs for formatting.
Syntax:
- Newline:
{NEWLINE}or{NL}(with optional count:{NL_3}) - Tab:
{TAB}(with optional count:{TAB_2})
# Insert newlines
python -m src.main --mode focus --input "Line 1{NL}Line 2{NL_2}Line 3"
# Insert tabs for indentation
python -m src.main --mode focus --input "Name:{TAB}Value{NL}Age:{TAB}25"To type literal curly braces, escape them with backslash:
# Output: "{literal braces}"
python -m src.main --mode focus --input "\{literal braces\}"
# Output: "Function: void func() {}"
python -m src.main --mode focus --input "Function: void func() \{\}"Combining multiple macro types:
python -m src.main --mode focus --input "
{SET_username=admin}
{WAIT_0.5}
{SPEED_0.1}
Username: {GET_username}{<enter>}
{WAIT_0.3}
{SPEED_0.15}
Password: {RANDOM_12}{<enter>}
{WAIT_1}
{MOUSE_MOVE_500_300}
{MOUSE_CLICK_left}
{WAIT_0.5}
{REPEAT_3}Processing{WAIT_0.5}{<backspace>+{WAIT_0.3}{/REPEAT}
Done!"Using loops, counters, and datetime:
python -m src.main --mode focus --input "
Log started at {DATETIME}
{NL_2}
{LOOP_5}
{TAB}{COUNTER}. Entry at {TIME}{NL}
{/LOOP}
{NL}
Log completed at {DATETIME}
"Type-Simulator can be compiled into standalone executables using Nuitka. This allows distribution without requiring Python or dependencies to be installed.
# Install Nuitka and development dependencies (if not already installed)
pip install -r requirements-dev.txt
# Or install just Nuitka for building
pip install nuitka
# Build using the provided script
cd build
./build_linux_x86.sh
# Result: dist/type_simulator (standalone executable)The build script will:
- Auto-detect the project structure
- Compile
src/main.pyusing Nuitka - Create a standalone, single-file executable in
dist/
You can also build manually with custom Nuitka options:
# Standalone build
nuitka --standalone --onefile \
--output-dir=dist \
--output-filename=type_simulator \
src/main.py
# With optimizations
nuitka --standalone --onefile \
--follow-imports \
--enable-plugin=pylint-warnings \
--output-dir=dist \
--output-filename=type_simulator \
src/main.pyThe build/ directory contains build automation:
build_linux_x86.sh- Build for Linux x86/x64build_all.py- Cross-platform build automation (experimental)
After building, the dist/type_simulator executable can be:
- Run directly without Python installation
- Distributed as a single file
- Used in CI/CD pipelines without dependency installation
# Run the built executable
./dist/type_simulator --mode focus --input "Hello from executable!" --profile humanNote: GitHub Releases may include pre-built executables for major versions. Check the Releases page for available downloads.
Type-Simulator works great in headless CI environments:
# GitHub Actions example
name: Demo Test
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y xvfb xterm xdotool xfonts-base
pip install -r requirements.txt
- name: Run typing demo
run: |
xvfb-run python -m src.main --mode gui --input "CI Demo" --statsExecute commands before typing starts:
# Start a screen recorder before typing
python -m src.main --mode focus --input "Recording this" \
--pre-launch-cmd "recordmydesktop --on-the-fly-encoding -o demo.ogv"
# Set up environment
python -m src.main --mode terminal --input "echo 'Test'" \
--pre-launch-cmd "export TEST_VAR=value"Use any editor or application:
# Use VS Code
python -m src.main --mode gui --editor-script "code" --input "VS Code text"
# Use nano
python -m src.main --mode gui --editor-script "xterm -e nano" --input "Nano text"
# Use emacs
python -m src.main --mode gui --editor-script "emacs" --input "Emacs text"
# Custom terminal
python -m src.main --mode terminal --editor-script "gnome-terminal --" --input "ls -la"The --input flag accepts both literal text and file paths:
# Type contents of a file
python -m src.main --mode focus --input demo/demo_macro.txt
# If the file doesn't exist, treats as literal text
python -m src.main --mode focus --input "This is literal text, not a file"Keep the editor open after typing:
# Wait 10 seconds before closing
python -m src.main --mode gui --input "Demo text" --wait 10
# Keep open indefinitely (use Ctrl+C to close)
python -m src.main --mode gui --input "Demo text" --wait 9999Solution: Install Python dependencies:
pip install -r requirements.txtNote: The package name is case-sensitive - it's PyAutoGUI in requirements.txt but imports as pyautogui.
Solution: Install system packages (Linux):
sudo apt-get install xvfb xterm xdotool xfonts-baseError: In direct mode, --output must be specified.
Solution: Always provide --output when using --mode direct:
python -m src.main --mode direct --output result.txt --input "Text"Solution: Make the executable file executable:
chmod +x dist/type_simulatorSolutions:
- Use
--dry-runto validate macro syntax without executing - Enable debug logging:
--log-level DEBUG - Check for proper escaping of literal braces with backslash
- Ensure macro syntax matches documentation (e.g.,
{REPEAT_3}not{REPEAT 3})
# Validate macro syntax
python -m src.main --mode direct --output test.txt \
--input "{REPEAT_3}Test{/REPEAT}" --dry-run --log-level DEBUGSolution:
- Ensure the target window is focused before running the command
- Add a wait at the start:
{WAIT_2}Your text here - Use
--pre-launch-cmdto focus the window programmatically
Solution: Adjust speed and variance:
# Slower typing
python -m src.main --mode focus --input "Slow" --speed 0.2 --variance 0.08
# Faster typing
python -m src.main --mode focus --input "Fast" --speed 0.03 --variance 0.01
# Or use profiles
python -m src.main --mode focus --input "Text" --profile slowEnable detailed logging for troubleshooting:
python -m src.main --mode focus --input "Debug test" --log-level DEBUG# Show help message
python -m src.main --help
# Show version
python -m src.main --version
# List available profiles
python -m src.main --list-profilesExtend the TextTyper implementation in src/type_simulator/text_typer/__main__.py to handle additional key sequences or commands. The macro parsing logic is in src/type_simulator/text_typer/parser.py.
Edit src/type_simulator/profiles.py to add your own typing profiles:
"custom": TypingProfile(
name="custom",
speed=0.06,
variance=0.03,
pause_probability=0.08,
pause_duration=0.25,
description="My custom typing style",
),The tool uses PyAutoGUI which adapts to different platforms automatically. Key names may vary:
- Windows:
winkey - Mac:
cmdkey - Linux:
superkey (orwin)
Contributions are welcome! Please follow these steps:
# Clone the repository
git clone https://github.com/djeada/Type-Simulator.git
cd Type-Simulator
# Install development dependencies
pip install -r requirements-dev.txt
# Install project in editable mode
pip install -e .# Run unit tests
pytest tests/unit_tests/
# Run end-to-end tests
pytest tests/e2e/
# Run all tests with coverage
pytest --cov=src tests/
# Run specific test file
pytest tests/unit_tests/test_type_simulator/test_text_typer/test_parser.py- Follow PEP 8 guidelines
- Use type hints where appropriate
- Add docstrings to functions and classes
- Keep functions focused and small
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Bug fixes
- New typing profiles
- Additional macro commands
- Platform-specific improvements
- Documentation improvements
- Test coverage improvements
- Performance optimizations
This project is licensed under the MIT License.
MIT License
Copyright (c) 2024 Type-Simulator Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- Built with PyAutoGUI for cross-platform automation
- Compiled with Nuitka for standalone executables
- Inspired by the need for realistic typing demonstrations and automation
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: This README and inline code documentation
Happy Typing! π