Metadata-Version: 2.1
Name: keystroke-transcriber
Version: 1.0.0
Summary: Records keypress events and converts them for replay on programmable USB HID devices
Home-page: https://github.com/eriknyquist/keystroke_transcriber
Author: Erik Nyquist
Author-email: eknyquist@gmail.com
License: Apache 2.0
Platform: UNKNOWN
Requires-Dist: keyboard
Requires-Dist: wheel

keystroke_transcriber: records your keystrokes and writes an Arduino sketch to replay the same keystrokes
---------------------------------------------------------------------------------------------------------

If you need to write arduino sketches for USB HID keyboard emulation (Digispark, Teensy, Ducky USB), then
this module might be useful to you.

This module records global keystroke events on your PC (when you tell it to),
and uses the recorded keystroke sequence to write the sketch for you.

Simply tell it which programmable USB HID keyboard platform you're using, and start
pressing keys. keystroke_transcriber will generate a sketch file for you. You can
even choose to maintain the timing between your original keypresses, if you want.

Limitations
-----------

Currently only supports Digispark: Support for Ducky USB and Teensy devices will be coming soon

keystroke_transcriber command-line arguments
--------------------------------------------

::

    usage: keystroke_transcriber [-h] [-p {oneshot,repeat-forever,repeat-n}]
                                 [-t {digispark}] [-o OUTPUT_FILE]
                                 [-n REPEAT_COUNT] [-D REPEAT_DELAY_MS]
                                 [-d EVENT_DELAY_MS] [-m] [-r RECORD_SECONDS] [-s]
                                 [-q]

    Records global keypress events until Ctrl-C is pressed (or until a fixed time
    has elapsed), and translates them into a program that replays those keypress
    events on some programmable USB HID device (e.g. Digispark)

    optional arguments:
      -h, --help            show this help message and exit
      -p {oneshot,repeat-forever,repeat-n}, --playback-type {oneshot,repeat-forever,repeat-n}
                            Set the playback style for recorded keystroke
                            sequences (default: oneshot)
      -t {digispark}, --target-type {digispark}
                            Set the type of programmable USB HID device to
                            generate output for (default: digispark)
      -o OUTPUT_FILE, --output-file OUTPUT_FILE
                            Write output to this file, instead of printing output
                            to the terminal (default: None)
      -n REPEAT_COUNT, --repeat-count REPEAT_COUNT
                            Sets how many times the recorded keystroke sequence
                            should be repeated (only used if --playback-type is
                            repeat-n) (default: 1)
      -D REPEAT_DELAY_MS, --repeat-delay-ms REPEAT_DELAY_MS
                            Sets delay between recorded keystroke sequence
                            repetitions, in milliseconds (only used if --playback-
                            type is repeat-n or repeat-forever) (default: 0)
      -d EVENT_DELAY_MS, --event-delay-ms EVENT_DELAY_MS
                            Sets delay between individual keystroke events, in
                            milliseconds (only used if --maintain-timing is False)
                            (default: 0)
      -m, --maintain-timing
                            Maintain timing between recorded keystrokes (default:
                            False)
      -r RECORD_SECONDS, --record-seconds RECORD_SECONDS
                            Record for this many seconds, instead of recording
                            until Ctrl-C is seen (default: None)
      -s, --translate-scan-codes
                            Attempt to translate PS/2 scan codes to USB HID usage
                            ID codes (default: True)
      -q, --quiet-keypresses
                            Don't print detected keypresses to the terminal
                            (default: False)


Example Digispark sketch generated by keystroke_transcriber
-----------------------------------------------------------

For this example, I ran keystroke_transcriber with the following arguments to record
keypress events until Ctrl+C, and generate a sketch for Digispark devices:

::

    python -m keystroke_transcriber -p oneshot -t digispark -m

Then, I performed the following keyboard / mouse actions:

#. Typed Ctrl+R (to open the "run" program)
#. Typed "notepad", followed by the Enter key (to open the Notepad application)
#. Typed "Hello, from keystroke_transcriber!!!!"
#. Clicked on the terminal window in which I originally ran keystroke_transcriber, to
   bring it back into focus, so the Ctrl+C signal in the next step would be sent to the
   program, instead of being sent to notepad (This step will not be recorded/replicated by
   keystroke_transcriber, since keystroke_transcriber records keypresses and not mouse activity,
   but it is necessary to successfully record keystroke sequences so I am including it anyway)
#. Typed Ctrl+C (to stop the recording)

After I pressed Ctrl+C, keystroke_transcriber provided the following Digispark sketch:

::

    // Auto-generated by keystroke_transcriber. Do not modify!

    #include "DigiKeyboard.h"

    #define NUM_EVENTS (81u)

    // Time taken to read the last event from PROGMEM and send it
    static unsigned long last_event_send_ms = 0u;

    // Holds all information required to replay a single keypress
    struct key_event
    {
        uint8_t key;
        uint8_t mods;
        uint16_t delay_before_ms;
    };

    // Holds a sequence of one or more keypress events to be replayed
    const struct key_event key_events[NUM_EVENTS] PROGMEM =
    {
        {0, MOD_GUI_LEFT, 0u}, {21u, MOD_GUI_LEFT, 229u}, {0, MOD_GUI_LEFT, 86u},
        {0, 0, 37u}, {17u, 0, 468u}, {18u, 0, 82u}, {0, 0, 107u}, {23u, 0, 42u},
        {8u, 0, 119u}, {0, 0, 98u}, {19u, 0, 70u}, {0, 0, 88u}, {4u, 0, 63u},
        {7u, 0, 68u}, {0, 0, 78u}, {40u, 0, 358u}, {0, 0, 145u},
        {0, MOD_SHIFT_LEFT, 526u}, {11u, MOD_SHIFT_LEFT, 79u},
        {0, MOD_SHIFT_LEFT, 59u}, {0, 0, 14u}, {8u, 0, 84u}, {0, 0, 46u},
        {15u, 0, 64u}, {0, 0, 53u}, {15u, 0, 81u}, {18u, 0, 39u}, {0, 0, 90u},
        {54u, 0, 86u}, {44u, 0, 84u}, {9u, 0, 62u}, {0, 0, 52u}, {21u, 0, 84u},
        {18u, 0, 49u}, {16u, 0, 34u}, {44u, 0, 79u}, {0, 0, 57u}, {14u, 0, 132u},
        {0, 0, 60u}, {8u, 0, 39u}, {0, 0, 46u}, {28u, 0, 83u}, {0, 0, 45u},
        {22u, 0, 16u}, {0, 0, 43u}, {23u, 0, 149u}, {21u, 0, 58u}, {0, 0, 58u},
        {18u, 0, 20u}, {14u, 0, 46u}, {0, 0, 57u}, {8u, 0, 25u}, {0, 0, 47u},
        {0, MOD_SHIFT_LEFT, 119u}, {45u, MOD_SHIFT_LEFT, 43u},
        {0, MOD_SHIFT_LEFT, 52u}, {0, 0, 38u}, {23u, 0, 158u}, {21u, 0, 35u},
        {4u, 0, 43u}, {0, 0, 64u}, {17u, 0, 126u}, {22u, 0, 38u}, {0, 0, 27u},
        {6u, 0, 107u}, {0, 0, 47u}, {21u, 0, 120u}, {0, 0, 46u}, {12u, 0, 0u},
        {5u, 0, 82u}, {8u, 0, 66u}, {21u, 0, 31u}, {0, 0, 53u},
        {0, MOD_SHIFT_LEFT, 143u}, {30u, MOD_SHIFT_LEFT, 92u},
        {0, MOD_SHIFT_LEFT, 58u}, {30u, MOD_SHIFT_LEFT, 83u},
        {0, MOD_SHIFT_LEFT, 44u}, {30u, MOD_SHIFT_LEFT, 138u},
        {0, MOD_SHIFT_LEFT, 36u}, {0, 0, 36u}
    };

    // Send a single keypress event to the USB host
    void send_key_event(const struct key_event *event)
    {
        if (event->delay_before_ms > last_event_send_ms)
        {
            DigiKeyboard.delay(event->delay_before_ms - last_event_send_ms);
        }

        DigiKeyboard.sendKeyPress(event->key, event->mods);
    }

    // Replay all keypress events stored in PROGMEM
    void replay_key_events()
    {
        for (unsigned i = 0u; i < NUM_EVENTS; i++)
        {
            struct key_event event;

            unsigned long start_time = millis();
            event.key = pgm_read_byte_near(&key_events[i].key);
            event.mods = pgm_read_byte_near(&key_events[i].mods);
            event.delay_before_ms = pgm_read_word_near(&key_events[i].delay_before_ms);
            send_key_event(&event);
            last_event_send_ms = millis() - start_time;
        }
    }

    void setup()
    {
        replay_key_events();
    }

    void loop()
    {

        DigiKeyboard.update();
    }

If you flash this sketch on to your Digispark, and plug the Digispark into a Windows
PC, you will see the keyboard activity I just described, complete with the timing of my original keypresses.


