Prerequisites

You will then need to obtain the source code for the Python implementation of the Nudgis API client
from this address: https://github.com/UbiCastTeam/nudgis-client/tags

Please ensure you check for updates to this code regularly to ensure the Nudgis API works correctly

Configuration file

Next, copy the sample JSON configuration file "config.json.example" to the examples directory as "config.json": 

  cd nudgis-client-1.1
  cp config.json.example examples/config.json

Finally, you need to edit the configuration file (config.json) by adding the API key for the account API_KEY which will run the script  and the address of your Nudgis server SERVER_URL :

{
"API_KEY": "XXX",
"CLIENT_ID": "python-api-client",
"PROXIES": {
"http": "",
"https": ""
},
"SERVER_URL": "https://XXX",
"UPLOAD_CHUNK_SIZE": 5242880,
"VERIFY_SSL": false
}

Retrieving the API key

You can find your API key on your Nudgis user profile page under My Profile View my API key:

To conclude this chapter, we strongly recommend that you create an account dedicated to the API, without a password, and with only the permissions required for the script being run. This account will not be able to log in to Nudgis (as the password is blank).

The site’s master API key must never be used in conjunction with the Nudgis API

Using scripts

The available scripts can be found in the project’s “examples” directory.

Firstly, to check that the configuration in the "config.json" file is correct and that you can communicate with your server, you need to run the script ping_server.py.

This script does not require any special permissions. The command should return a success message, along with the version number of your Nudgis server. A will be worded as follows:

cd examples
python3 ping_server.py config.json 
{'success': True, 'mediaserver': '13.0.1'}

Now that this test has been successfully completed, you can run the scripts in the examples directory. We’ll begin exploring them by introducing scripts that help manage your server’s storage by freeing up where possible.

Video lifecycle

As your server’s disk space is limited, you will need to regularly clear out your videos. This task is made much easier by the scripts shown below. However, they must be used with the utmost care, as they will permanently delete data from your server. This is why these scripts allow you to carry out dry runs to verify the deletion conditions. Using them requires permission to access and delete media from your catalogue.

The first script available to you is delete_video_qualities.py . It allows you to delete unwanted video qualities from a channel, or from a CSV file. Once the script has been run, only the best quality of the MP4 resource (or MP3, where applicable) is retained. You must also have "Resource Files" editing permission to run this script.

However, you can also choose which resolutions to delete individually. For example, to simulate the deletion of the 360p qualities for a channel (represented in the script by its identifier, or OID), you must run the following command :

python delete_video_qualities.py --conf config.json --channel c12640c68e63b949rq65 --qualities "360" 

Once the script has finished running, the amount of disk space that will be freed up is displayed as follows:

Would have freed 1 GB (29 resources) if run with "--delete".

If you are happy with the result, you can actually carry out the deletion by adding the option --delete

python delete_video_qualities.py --conf config.json --channel c12640c68e63b949rq65 --qualities "360" --delete

The following command displays details of the script’s options: 

python delete_video_qualities.py --help

The second script shown, cleanup_unwatched_media.py, allows you to delete unwatched media. In addition to permissions to access and delete media, the global permission "Can view all statistics" and the "Resource files" ".

For example, the command to simulate the deletion of media items that have 10 views (or fewer than 10) for the year 2023 and move them to the bin will be as follows:

python cleanup_unwatched_media.py --conf config.json --start-date 2023-01-01 --end-date "2023-12-31" --max-views 10 --action trash

You can run the script on a specific channel, rather than processing the entire catalogue, by adding the parameter --channel-oid with your channel’s ID

python cleanup_unwatched_media.py --conf config.json --start-date 2023-01-01 --end-date "2023-12-31" --max-views 10 --action trash --channel-oid c12664e08d3623prveob

Once the script has finished running, the amount of disk space that will be freed up is displayed as follows:

Trashing these VODs would have freed up to 61.4MB

If you are happy with the result, you can actually carry out the deletion by adding the parameter --apply : 

python cleanup_unwatched_media.py --conf config.json --start-date 2023-01-01 --end-date "2023-12-31" --max-views 10 --action trash --channel-oid c12664e08d3623prveob --apply

The following command displays details of the script’s options: 

python cleanup_unwatched_media.py --help

To conclude this chapter, let’s take a look at the script mass_delete.py, which allows you to perform a bulk deletion by specifying a list of video IDs with a CSV file, with the IDs in the first column. Lines beginning with "#" are ignored.

A video’s ID can also be found in the media’s permalink of the media

This script requires the additional global permission "Can edit " and the "Resource files" edit permission. The following command runs the script:

python mass_delete.py --conf config.json --csv ./videos-id.csv

The result should be similar to the following line: 

Deleting these VODs would have freed 4.1 GB

If you are happy with the result, you can actually carry out the deletion by adding the parameter --apply : 

python mass_delete.py --conf config.json --csv ./videos-id.csv --apply

If you do not want the media files to be moved to the bin, add the parameter --permanent. Please note , however, when using this option, as deletion will then be immediate and irreversible: 

python mass_delete.py --conf config.json --csv ./videos-id.csv --apply --permanent

The following command displays details of the script’s options: 

python mass_delete.py --help

Statistics and metrics

A wealth of information on using the portal is available in the site interface, as described in the article Statistics in Nudgis.  However, it is possible to go even further by using the script csv_media_stats.py , which allows you to extract metrics that are not available in the . For example, you can obtain information on the breakdown of your media by type, duration, and data by contributor, such as the top ten significant contributors in terms of media uploaded, for instance.

To analyse this data, you will first need to generate it by running the script csv_media_generate.py. You must have the global permission "Can edit site settings" to run this script, the command for which will generate a CSV file:

python csv_media_generate.py config.json 

Once the file has been generated, you can run an analysis on it using the :

python csv_media_stats.py --input media-monserveur.fr.csv 

Furthermore, it is possible to retrieve a speaker’s list of media files in CSV format. Simply specify the speaker’s email address using the --target-email using the script list_media_for_speaker.py. You must have permission to access and edit media in the catalogue to use this script:

python list_media_for_speaker.py --conf config.json --target-email "test@ubicast.eu"

Reversibility

The Nudgis API also offers the option to retrieve data for a backup or migration. The script backup_media.py will generate a ZIP archive containing the video’s metadata as well as the best quality version of the video resource. This script requires editing permissions "Resource files" and "Community settings". To back up media before 2024, use the following command: 

python backup_media.py --conf config.json --date 2024-01-01 --tree

By default, the backup will be saved to the "backups" directory

To delete the backed-up files, add the option --delete . Please , however, when using this option, as deletion will then be immediate and irreversible: 

python backup_media.py --conf config.json --date 2024-01-01 --tree --delete

The following command displays details of the script’s options: 

python backup_media.py --help

The following script, backup_channel_recursive.py, allows you to restrict the backup by channel by specifying the channel ID the channel, but will also perform a default backup to the "backups" directory:

 python backup_channel_recursive.py --conf config.json --channel c12640c68e63b949rq65

To restore the backup on Nudgis, simply use the script restore_media.py specifying the directory containing your backup. The media files are restored to their original channel: 

python restore_media.py --conf config.json --path backups

You can also restore media to another existing channel on your Nudgis server by using the --channelfollowed by the corresponding OID. In this case, the media will be restored to that channel :

  python restore_media.py --conf config.json --path backups --channel c1266553ef1690qfgln9 --tree

python download_all_original_files.py config.json VideosHD