NAME

App::Textcast - Light weight text casting

SYNOPSIS

  use App::Textcast qw(record_textcast play_textcast) ;
  
  record_textcast(COMMAND => 'bash') ;
  play_textcast(TEXTCAST_DIRECTORY => $input_directory) ;

DESCRIPTION

What's a textcast?

It's a screencast of a terminal session. The idea is to record the terminal session and replay it in another terminal without loosing resolution, as screencasts do, nor using much disk space due to conversion from text to video. The terminal session can run a shell or any other program.

Why textcasts?

• Size, I did a screen cast of a completion script, the size was 1.5 MB and it didn't look as good as the terminal. The same textcast was 10 KB (yes, 10 Kilo Bytes) and it looked good.
• It is not possible to make a screencast of a real terminal, maybe via vnc but that's already too complicated
• Documentation. I believe it is sometimes better to show "live" documentation than static text. I am planning to write a module that plays a textcast embedded in ones terminal. The text cast being controlled by the application that displays help. I also believe that it could be used as a complement to showing static logs or screenshots; an example is when someone describe a problem on IRC. Seeing what is being done is sometimes very helpful.
• Editing. possibility to add message possibility to add sound possibility to extend the time an image or a range of images is displayed concatenate text casts (and their indexes) remove portions of a text cast name part of the text cast (shows in the index)

DOCUMENTATION

See record_textcast and play_textcast subbroutines.

SCRIPTS

Two commands, record_textcast and play_textcast, are installed on your computer when you install this module. Use them to record and replay your text casts.

Output

The textcast is a serie of files recorded in a directory. Tar/gzip the files before you send them. the compression ratio averages 95%.

SUBROUTINES/METHODS

record_textcast( %named_arguments )

Records the terminal output of a command. The output is stored as a set of files in a directory. The directory is later passed as argument to play_textcast for display.

  use App::Textcast 'record_textcast' ;
  
  record_textcast
        (
        COMMAND => 'bash',
        OUTPUT_DIRECTORY => shift @ARGV,
        COMPRESS => $compress,
        COLUMNS => $columns,
        ROWS => $rows,
        ) ;

Arguments

The arguments are named, order is not important.

• COMMAND => $string - the name of the command to tun in a terminal. You most probably wan to run bash or sh
• OUTPUT_DIRECTORY => $directory_path - Optional - the path to the directory where the textcast is to be recorded. This subroutine will create a directory if this option is not set. if this option is set, the directory should not exist.
• COMPRESS => $boolean - Not implemented
• COLUMNS => $integer - Optional - Number of columns in the terminal. The current terminal columns number is used if this argument is not set.
• ROWS => $integer - Optional - Number of rows in the terminal. The current terminal rows number is used if this argument is not set.

Returns - Nothing

Exceptions

• See check_output_directory
• see create_vt102_sub_process
• disk full error

See scripts/record_textcast.

[p] check_output_directory( $output_directory)

Check that the given output directory does not exist. If $output_directory is not defined, a directory name is generated.

Arguments

• $output_directory - The name of the directory where the textcast is recorded

Returns - The directory where the textcast is recorded.

Exceptions

• Textcast directory already exists
• Path too long - length must be under 256 characters.
• Invalid path - Path can only contain alphanumerics and path separator.

play_textcast( %named_arguments)

Loads, checks, and initiates the textcast replay. Displays information after the textcast replay.

  use App::Textcast 'play_textcast' ;
  
  play_textcast
        (
        TEXTCAST_DIRECTORY => $input_directory,
        OVERLAY_DIRECTORY => $overlay_directory,
        DISPLAY_STATUS => $display_status,
        START_PAUSED => $start_paused,
        ) ; 

Arguments

• TEXTCAST_DIRECTORY - String - directory containing the textcast
• OVERLAY_DIRECTORY - not implemented
• DISPLAY_STATUS - Boolean -
• START_PAUSED - not implemented

Returns - Nothing

Exceptions

• Terminal too small
• interrupted by user
• load_index

[p] display_text_cast_data($input_directory, \@screenshot_information, \%display_status )

Plays a screencast.

Arguments

• $input_directory - String - directory containing the textcast
• \@screenshot_information - see load_index
• \%display_status -

  DISPLAY - Boolean - status is displayed during the replay if this is set

  ROW - row where the status is displayed

  COLUMNS - column where the status is displayed

Returns - A list containing

• $total_play_time
• $played_frames
• \@skipped_frames

Exceptions - None

[p] print_play_information($total_play_time, $played_frames, \@skipped_frames)

Displays information about the textcast replay.

  print_play_information
        (
        $total_play_time,
        $total_frames,
        $played_frames,
        \@skipped_frames,
        ) ;

Arguments

• $total_play_time - Float - play time in seconds
• $played_frames - Integer - number of framed played, maybe less than $total_frames
• \@skipped_frames - Integer - number of frames skipped because they couldn't be found

Returns - Nothing

Exceptions - None

[p] status($status, $status_row, $status_column)

Displays a status on the status line.

Arguments

• $status - String to be displayed on the terminal
• $status_row - Integer - row position for the status
• $status_column - Integer - column position for the status

Returns - Nothing

Exceptions - None

[p] position_cursor($row, $column)

Create an ANSI command to position the cursor on the terminal.

Arguments

• $row - Integer - row position for the status
• $column - Integer - column position for the status

Returns - A string containing the ANSI command.

Exceptions - None

See xxx.

[p] load_index($input_directory)

Loads the screencast meta-data.

Arguments

• $input_directory - The directory containing the textcast

Returns - The screencast meta-data, see the index file for format information.

Exceptions

• Index not found
• Invalid data in index

[p] create_vt102_sub_process($shell_command, $columns, $rows)

Arguments

• $shell_command, $columns, $rows -

Returns - a vt_process handle

Exceptions

[p] close_vt102_sub_process( $vt_process)

Arguments

• $vt_process - vt_process handle created by create_vt102_sub_process

Returns - Nothing

Exceptions - None

[p] create_vt102_terminal($pty, $columns, $rows)

Arguments

$pty, $columns, $rows -

Returns - $vt, $terminal_change_buffer

Exceptions - None

[p] vt_output($vtobject, $type, $arg1, $arg2, $private)

Callback for OUTPUT events - for Term::VT102.

Arguments

$vtobject, $type, $arg1, $arg2, $private -

Returns - Nothing

Exceptions - Nothing

See Term::VT102.

[p] vt_rowchange($vtobject, $type, $arg1, $arg2, $private)

Callback for ROWCHANGE events. This just sets a time value for the changed row using the private data as a hash reference - the time represents the earliest that row was changed since the last screen update.

Arguments

$vtobject, $type, $arg1, $arg2, $private -

Returns - Nothing

Exceptions - Nothing

See Term::VT102.

[p] vt_changeall($vtobject, $type, $arg1, $arg2, $private)

Callback to trigger a full-screen repaint.

Arguments

$vtobject, $type, $arg1, $arg2, $private -

Returns - Nothing

Exceptions - None

See Term::VT102.

[p] create_child_process($shell_command, $pty, $vt)

Creqtes a child process to run a command in.

Arguments

$shell_command, $pty, $vt -

Returns - Nothing

Exceptions - Can not fork to run sub process

See xxx.

[p] run_child_process($command, $pty, $vt)

Arguments

$command, $pty, $vt -

Returns - Nothing

Exceptions - Error redirecting streams

[p] check_sub_process_output( $vt_process)

Check the sub process output.

Arguments

• $vt_process -

Returns - $eof, $screen_data, $cursor_x, $cursor_y

Exceptions - None

BUGS AND LIMITATIONS

None so far.

AUTHOR

        Nadim ibn hamouda el Khemir
        CPAN ID: NH
        mailto: nadim@cpan.org

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc App::Textcast

You can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/App-Textcast

• RT: CPAN's request tracker

  Please report any bugs or feature requests to L <bug-app-textcast@rt.cpan.org>.

  We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.

• Search CPAN

  http://search.cpan.org/dist/App-Textcast

SEE ALSO

screen (1), script(1), aewan, vte(1), evilvte(1).