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 -
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
Returns - $vt, $terminal_change_buffer
Exceptions - None
[p] vt_output($vtobject, $type, $arg1, $arg2, $private)
Callback for OUTPUT events - for Term::VT102.
Arguments
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
Returns - Nothing
Exceptions - Nothing
See Term::VT102.
[p] vt_changeall($vtobject, $type, $arg1, $arg2, $private)
Callback to trigger a full-screen repaint.
Arguments
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
Returns - Nothing
Exceptions - Can not fork to run sub process
See xxx.
[p] run_child_process($command, $pty, $vt)
Arguments
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.orgLICENSE 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::TextcastYou can also look for information at:
AnnoCPAN: Annotated CPAN documentation
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
SEE ALSO
screen (1), script(1), aewan, vte(1), evilvte(1).