Development Resource

From The Neuros Technology Wiki

Jump to: navigation, search

This page will hold in the future pointers to detailed documentation to the API that out system offers to application developers. Right now, it's a collection of documentation on how you can control the system from command line using some utility apps that we developed for this purpose, and which you can use to understand how to perform the same operations yourself from your own apps (if you don't want to call the utilities instead).

There's also a section on VLC, which will eventually run in server mode, and be accessed via DBUS API. However for now, we show how to use it to do some multimedia tasks supported by the OSD2 by running it as normal application.

If you instead are interested in setting up the system from scratch, please visit the OSD2 system build page.


OSD2 Development - Command Line Manual

This manual is meant to explain to you the osd2-specific command line applications and tools that you can use to control the device.

Audio/Video commands

Switching output resolution and port

By default, the osd2 will boot with output set to PAL over composite connector. If you want to change this, here's how you do it: mode <MODE>

Where <MODE> is one of the following: ntsc,pal,480p,720p,1080i

If you use ntsc or pal, the composite output will be enable automatically, and hdmi and component disabled (we don't support ntsc/pal over these connectors, at the moment, we may add it in the future).

If you use any of the other "HD" resolutions, composite output will be disabled and both hdmi and component will be enabled automatically. NOTE: at the moment 480p resolution isn't working, we still need to fix it.

Capturing input and displaying it with pass-through

If you have connected any of the composite inputs or the component input connector, and you're feeding a signal on one of them, you will be able to see the same signal on the currently active output.

video-demo <PLANE> <INPUT> <INPUT_MODE>

Where <PLANE> is either vid0 or vid1. Typically vid1 give better display than vid0, for some reason we are still looking into. However vid1 will work only if the current resolution (not the input's video resolution) is ntsc or pal. Don't use osd0 or osd1 planes as you will see only garbage, as they are not fit to display video.

<INPUT> is the input connector you want to use. Supported values are:

  • 0: back panel composite input
  • 1: front panel composite input
  • 2: back panel component input

<INPUT_MODE> should match precisely the input mode of the video signal that you want to view. It has the same values as the <MODE> parameter for previous commands.

Capturing output and listening to it with pass-through

To do the same pass-through operation, but this time with audio, you will need to run the following command:

audio_test -i<INPUT>

Where input is one of the following:

  • line1: back panel composite input
  • line2: front panel composite input
  • line3: back panel audio separate audio connectors

Right now, the output is always sent to the back panel composite connector audio output.

To quit the application, you need to press CTRL+C.

Please note that you can run both audio_test and video-demo by running one of them with ` &` (space and ampersand) at the end of the command line. This will leave the program running in background. To stop it you will need to use the `kill` or `killall` commands to terminate it.

More video output control commands

Switching planes

The osd2 has various output "planes", or "layers", where Linux or the DSP can send output. The commands above switch plane automatically, you don't need to do it manually, but for some of the commands in the next chapters, you will need to do it manually.

To switch one plane on and off, you use this command:

fb-demo <PLANE> enable <STATUS>

The <PLANE> can be:

  • osd0: bitmap plane, usually used to display the user interface. By default display either the Linux "Tux" penguin logo, or Neuros' own "Jerusha" duck mascot.
  • osd1: "attribute" plane, this is not supposed to be displayed to the user, it's a control plane used internally to alter the appearence of the other planes. if displayed, the contents are meaningless to the human eye most of the time.
  • vid0: video plane, this is where by default video is displayed when played with vlc. display a color pattern by default
  • vid1: alternative video plane, for some reason give better quality when used for ntsc or pal (see below)

Where <STATUS> is 0 (disabled) or 1 (enabled) and <PLANE> is one of the planes listed above.

There's also a shortcut, if you want to enable one plane and disable all others: plane <PLANE>

Right now, if you want to play a video with vlc (see below), use this shortcut and enable the vid0 plane. If you want to see the user interface, use it with osd0 plane.

User interface overlay

Sometimes it is useful to display the user interface overlaid with the video signal. To do this, the simplest way is to use video-demo to start the video pass-through with the correct options, then enable again the osd0 plane with fb-demo.

You will see that by default the image displayed there, the duck, will be partially transparent with teh video below it. To change the level of transparency, you can use the following command:

fb-demo osd0 transp <ENABLE> <LEVEL>

Where <ENABLE> is 1 or 0 and turn on or off transparency entirely. <LEVEL> is a number from 0 to 7, where 7 is the same as no transparency at all (you won't see the video below), and 0 is full transparency (you won't see the user interface plane, only the video).

Transparency does not apply to the entire plane, but only on the pixels on the plane that of a selected transparent color. You can choose this color with the following command:

fb-demo osd0 trcolor <COLOR>

Color is a number representing a color value in rgb888 format (e.g. 0 is black, and 16777215 (0xFFFFFF) is white).

Other misc useful commands

Mounting NFS Shares

To mount NFS shares, you use the regular `mount` command, however you need to specify some specific options to ensure compatibility with osd2's nfs implementation. Suppose you want to mount a share on /media/nfs (a directory that you created for this purpose, the read-write file system allow you that):

mount -t nfs -o nolock,nfsvers=3,udp /media/nfsvers

Obviously replace IP address and server-side path with your own real ones. If the mount is successful, the command returns almost immediately with no message, and you can see the files on the share with `ls` command, if any.

VLC Command line usage examples

Basics and common options

To run vlc, it's always better to use the `` helper, and add parameters to it. This helper contain a number of options that are useful or mandatory on the osd2 plaform, so we don't guarantee operation if not using it.

Some options that you can always pass to the script, in addition to specific ones, are shown below. They will be omitted from the following examples, but you can add them anytime.

--control logger --logfile /tmp/vlc.log

This will force vlc to append its output to a log file on a writeable disk, which is useful to paste somewhere or email to support in case of issues. Please notice that the file is appended, so be sure to delete it when you just want to log something that is giving you an error, to avoid confusion.

--no-audio --v4l2-audio-method 0

This will disable audio input and output for vlc. Please be aware that right now you need this for most of the commands below. This is because of audio driver issues that we are still trying to resolve, that most of the time confuse so much vlc that it's not able to do its job. Disabling audio prevent this to happen and it is unfortunately a necessary measure, until these issues are fixed.

Playback of media file

Simply pass the URL of the video to the script (please notice that for now, you can't play files with spaces in the name this way): /media/something/yourvideo.mp4

You can experiment with various formats, the ones that should be supported without issues are mpeg4 and mpeg2, and h.264 should be coming up too. Please notice that if something does't work well, try again with the options to disable audio (see above).

By default the movie will be resized to screen size (or the largest size that the upscaler is able to accomodate if there's too much difference). You can force playback in original resolution (with letterboxing) using the following option:


Also please notice that if you the video is slow or completely jerky, check the log file, and if you notice some lines talking about davinci decoder errors, then you're using software decoder fallback. This is not really meant to be used, and it simply mean that either we don't support your video format that you're trying to play, or that something's wrong on the unit.

Pass-through using VLC

To capture from source and display on output, just like the video-demo application or audio_test application do, you can use this command line: v4l2:// -V fb --no-audio --v4l2-audio-method 0 --v4l2-input 0

You can change the last parameter to the same values of the <INPUT> parameter of video-demo, to select a different capture source.

Please notice that you MUST use the audio disable options to run this command successfully, for now.

Recording in mpeg4 --no-audio --v4l2-audio-method 0 --sout "#transcode{vcodec=mp4v}:std{access=file,mux=mp4,dst=/media/yourmedia/output.mp4}" v4l2:// --v4l2-input 0

This will capture a file in mpeg4 format, with no audio (the input parameter works like described above). You will be able to play back this same file on the osd2 without a problem.

Due to limitation of the codecs, this works only with ntsc or pal input for now.

Recording in h.264 --no-audio --v4l2-audio-method 0 --sout "#transcode{vcodec=h264}:std{access=file,mux=mp4,dst=/media/yourmedia/output.mp4}" v4l2:// --v4l2-input 0

Works exactly as mpeg4 recording. The difference is that currently you can't use osd2 to play back the video you just recorded due to a bug we're working to fix. The video plays fine on the PC however.

Personal tools